<!doctype html><html lang="en">
 <head>
  <meta content="text/html; charset=utf-8" http-equiv="Content-Type">
  <title>CSS Custom Properties for Cascading Variables Module Level 1</title>
  <meta content="width=device-width, initial-scale=1, shrink-to-fit=no" name="viewport">
  <meta content="testing" name="csswg-work-status">
  <meta content="ED" name="w3c-status">
  <meta content="This module introduces cascading variables as a new primitive value type that is accepted by all CSS properties, and custom properties for defining them." name="abstract">
  <link href="../default.css" rel="stylesheet" type="text/css">
  <link href="../csslogo.ico" rel="shortcut icon" type="image/x-icon">
<style>
  body {
    background: url("https://www.w3.org/StyleSheets/TR/logo-ED") top left no-repeat;
  }
  </style>
  <link href="https://www.w3.org/TR/css-variables-1/" rel="canonical">
<script defer src="https://test.csswg.org/harness/annotate.js#!css-variables-1_dev/css-variables-1" type="text/javascript"></script>
<style>/* style-md-lists */

/* This is a weird hack for me not yet following the commonmark spec
   regarding paragraph and lists. */
[data-md] > :first-child {
    margin-top: 0;
}
[data-md] > :last-child {
    margin-bottom: 0;
}</style>
<style>/* style-selflinks */

.heading, .issue, .note, .example, li, dt {
    position: relative;
}
a.self-link {
    position: absolute;
    top: 0;
    left: calc(-1 * (3.5rem - 26px));
    width: calc(3.5rem - 26px);
    height: 2em;
    text-align: center;
    border: none;
    transition: opacity .2s;
    opacity: .5;
}
a.self-link:hover {
    opacity: 1;
}
.heading > a.self-link {
    font-size: 83%;
}
li > a.self-link {
    left: calc(-1 * (3.5rem - 26px) - 2em);
}
dfn > a.self-link {
    top: auto;
    left: auto;
    opacity: 0;
    width: 1.5em;
    height: 1.5em;
    background: gray;
    color: white;
    font-style: normal;
    transition: opacity .2s, background-color .2s, color .2s;
}
dfn:hover > a.self-link {
    opacity: 1;
}
dfn > a.self-link:hover {
    color: black;
}

a.self-link::before            { content: "¶"; }
.heading > a.self-link::before { content: "§"; }
dfn > a.self-link::before      { content: "#"; }</style>
<style>/* style-counters */

body {
    counter-reset: example figure issue;
}
.issue {
    counter-increment: issue;
}
.issue:not(.no-marker)::before {
    content: "Issue " counter(issue);
}

.example {
    counter-increment: example;
}
.example:not(.no-marker)::before {
    content: "Example " counter(example);
}
.invalid.example:not(.no-marker)::before,
.illegal.example:not(.no-marker)::before {
    content: "Invalid Example" counter(example);
}

figcaption {
    counter-increment: figure;
}
figcaption:not(.no-marker)::before {
    content: "Figure " counter(figure) " ";
}</style>
<style>/* style-autolinks */

.css.css, .property.property, .descriptor.descriptor {
    color: #005a9c;
    font-size: inherit;
    font-family: inherit;
}
.css::before, .property::before, .descriptor::before {
    content: "‘";
}
.css::after, .property::after, .descriptor::after {
    content: "’";
}
.property, .descriptor {
    /* Don't wrap property and descriptor names */
    white-space: nowrap;
}
.type { /* CSS value <type> */
    font-style: italic;
}
pre .property::before, pre .property::after {
    content: "";
}
[data-link-type="property"]::before,
[data-link-type="propdesc"]::before,
[data-link-type="descriptor"]::before,
[data-link-type="value"]::before,
[data-link-type="function"]::before,
[data-link-type="at-rule"]::before,
[data-link-type="selector"]::before,
[data-link-type="maybe"]::before {
    content: "‘";
}
[data-link-type="property"]::after,
[data-link-type="propdesc"]::after,
[data-link-type="descriptor"]::after,
[data-link-type="value"]::after,
[data-link-type="function"]::after,
[data-link-type="at-rule"]::after,
[data-link-type="selector"]::after,
[data-link-type="maybe"]::after {
    content: "’";
}

[data-link-type].production::before,
[data-link-type].production::after,
.prod [data-link-type]::before,
.prod [data-link-type]::after {
    content: "";
}

[data-link-type=element],
[data-link-type=element-attr] {
    font-family: Menlo, Consolas, "DejaVu Sans Mono", monospace;
    font-size: .9em;
}
[data-link-type=element]::before { content: "<" }
[data-link-type=element]::after  { content: ">" }

[data-link-type=biblio] {
    white-space: pre;
}</style>
<style>/* style-dfn-panel */

.dfn-panel {
    position: absolute;
    z-index: 35;
    height: auto;
    width: -webkit-fit-content;
    width: fit-content;
    max-width: 300px;
    max-height: 500px;
    overflow: auto;
    padding: 0.5em 0.75em;
    font: small Helvetica Neue, sans-serif, Droid Sans Fallback;
    background: #DDDDDD;
    color: black;
    border: outset 0.2em;
}
.dfn-panel:not(.on) { display: none; }
.dfn-panel * { margin: 0; padding: 0; text-indent: 0; }
.dfn-panel > b { display: block; }
.dfn-panel a { color: black; }
.dfn-panel a:not(:hover) { text-decoration: none !important; border-bottom: none !important; }
.dfn-panel > b + b { margin-top: 0.25em; }
.dfn-panel ul { padding: 0; }
.dfn-panel li { list-style: inside; }
.dfn-panel.activated {
    display: inline-block;
    position: fixed;
    left: .5em;
    bottom: 2em;
    margin: 0 auto;
    max-width: calc(100vw - 1.5em - .4em - .5em);
    max-height: 30vh;
}

.dfn-paneled { cursor: pointer; }
</style>
<style>/* style-syntax-highlighting */

.highlight:not(.idl) { background: hsl(24, 20%, 95%); }
code.highlight { padding: .1em; border-radius: .3em; }
pre.highlight, pre > code.highlight { display: block; padding: 1em; margin: .5em 0; overflow: auto; border-radius: 0; }
c-[a] { color: #990055 } /* Keyword.Declaration */
c-[b] { color: #990055 } /* Keyword.Type */
c-[c] { color: #708090 } /* Comment */
c-[d] { color: #708090 } /* Comment.Multiline */
c-[e] { color: #0077aa } /* Name.Attribute */
c-[f] { color: #669900 } /* Name.Tag */
c-[g] { color: #222222 } /* Name.Variable */
c-[k] { color: #990055 } /* Keyword */
c-[l] { color: #000000 } /* Literal */
c-[m] { color: #000000 } /* Literal.Number */
c-[n] { color: #0077aa } /* Name */
c-[o] { color: #999999 } /* Operator */
c-[p] { color: #999999 } /* Punctuation */
c-[s] { color: #a67f59 } /* Literal.String */
c-[t] { color: #a67f59 } /* Literal.String.Single */
c-[u] { color: #a67f59 } /* Literal.String.Double */
c-[cp] { color: #708090 } /* Comment.Preproc */
c-[c1] { color: #708090 } /* Comment.Single */
c-[cs] { color: #708090 } /* Comment.Special */
c-[kc] { color: #990055 } /* Keyword.Constant */
c-[kn] { color: #990055 } /* Keyword.Namespace */
c-[kp] { color: #990055 } /* Keyword.Pseudo */
c-[kr] { color: #990055 } /* Keyword.Reserved */
c-[ld] { color: #000000 } /* Literal.Date */
c-[nc] { color: #0077aa } /* Name.Class */
c-[no] { color: #0077aa } /* Name.Constant */
c-[nd] { color: #0077aa } /* Name.Decorator */
c-[ni] { color: #0077aa } /* Name.Entity */
c-[ne] { color: #0077aa } /* Name.Exception */
c-[nf] { color: #0077aa } /* Name.Function */
c-[nl] { color: #0077aa } /* Name.Label */
c-[nn] { color: #0077aa } /* Name.Namespace */
c-[py] { color: #0077aa } /* Name.Property */
c-[ow] { color: #999999 } /* Operator.Word */
c-[mb] { color: #000000 } /* Literal.Number.Bin */
c-[mf] { color: #000000 } /* Literal.Number.Float */
c-[mh] { color: #000000 } /* Literal.Number.Hex */
c-[mi] { color: #000000 } /* Literal.Number.Integer */
c-[mo] { color: #000000 } /* Literal.Number.Oct */
c-[sb] { color: #a67f59 } /* Literal.String.Backtick */
c-[sc] { color: #a67f59 } /* Literal.String.Char */
c-[sd] { color: #a67f59 } /* Literal.String.Doc */
c-[se] { color: #a67f59 } /* Literal.String.Escape */
c-[sh] { color: #a67f59 } /* Literal.String.Heredoc */
c-[si] { color: #a67f59 } /* Literal.String.Interpol */
c-[sx] { color: #a67f59 } /* Literal.String.Other */
c-[sr] { color: #a67f59 } /* Literal.String.Regex */
c-[ss] { color: #a67f59 } /* Literal.String.Symbol */
c-[vc] { color: #0077aa } /* Name.Variable.Class */
c-[vg] { color: #0077aa } /* Name.Variable.Global */
c-[vi] { color: #0077aa } /* Name.Variable.Instance */
c-[il] { color: #000000 } /* Literal.Number.Integer.Long */
</style>
 <body class="h-entry">
  <div class="head">
   <p data-fill-with="logo"><a class="logo" href="https://www.w3.org/"> <img alt="W3C" height="48" src="https://www.w3.org/StyleSheets/TR/2016/logos/W3C" width="72"> </a> </p>
   <h1 class="p-name no-ref" id="title">CSS Custom Properties for Cascading Variables Module Level 1</h1>
   <h2 class="no-num no-toc no-ref heading settled" id="subtitle"><span class="content">Editor’s Draft, <time class="dt-updated" datetime="1970-01-01">1 January 1970</time></span></h2>
   <details>
    <summary>Specification Metadata</summary>
    <div data-fill-with="spec-metadata">
     <dl>
      <dt>This version:
      <dd><a class="u-url" href="https://drafts.csswg.org/css-variables/">https://drafts.csswg.org/css-variables/</a>
      <dt>Latest published version:
      <dd><a href="https://www.w3.org/TR/css-variables-1/">https://www.w3.org/TR/css-variables-1/</a>
      <dt>Previous Versions:
      <dd><a href="https://www.w3.org/TR/2015/CR-css-variables-1-20151203/" rel="prev">https://www.w3.org/TR/2015/CR-css-variables-1-20151203/</a>
      <dd><a href="https://www.w3.org/TR/2014/WD-css-variables-1-20140506/" rel="prev">https://www.w3.org/TR/2014/WD-css-variables-1-20140506/</a>
      <dd><a href="https://www.w3.org/TR/2013/WD-css-variables-1-20130620/" rel="prev">https://www.w3.org/TR/2013/WD-css-variables-1-20130620/</a>
      <dd><a href="https://www.w3.org/TR/2013/WD-css-variables-20130312/" rel="prev">https://www.w3.org/TR/2013/WD-css-variables-20130312/</a>
      <dd><a href="https://www.w3.org/TR/2012/WD-css-variables-20120410/" rel="prev">https://www.w3.org/TR/2012/WD-css-variables-20120410/</a>
      <dt>Test Suite:
      <dd><a href="http://test.csswg.org/suites/css-variables-1_dev/nightly-unstable/">http://test.csswg.org/suites/css-variables-1_dev/nightly-unstable/</a>
      <dt class="editor">Editor:
      <dd class="editor p-author h-card vcard" data-editor-id="42199"><a class="p-name fn u-url url" href="http://xanthir.com/contact">Tab Atkins Jr.</a> (<span class="p-org org">Google</span>)
      <dt>Suggest an Edit for this Spec:
      <dd><a href="https://github.com/w3c/csswg-drafts/blob/master/css-variables-1/Overview.bs">GitHub Editor</a>
      <dt>Issue Tracking:
      <dd><a href="https://github.com/w3c/csswg-drafts/labels/css-variables-1">GitHub Issues</a>
     </dl>
    </div>
   </details>
   <div data-fill-with="warning"></div>
   <p class="copyright" data-fill-with="copyright"><a href="https://www.w3.org/Consortium/Legal/ipr-notice#Copyright">Copyright</a> © 1970 <a href="https://www.w3.org/"><abbr title="World Wide Web Consortium">W3C</abbr></a><sup>®</sup> (<a href="https://www.csail.mit.edu/"><abbr title="Massachusetts Institute of Technology">MIT</abbr></a>, <a href="https://www.ercim.eu/"><abbr title="European Research Consortium for Informatics and Mathematics">ERCIM</abbr></a>, <a href="https://www.keio.ac.jp/">Keio</a>, <a href="https://ev.buaa.edu.cn/">Beihang</a>). W3C <a href="https://www.w3.org/Consortium/Legal/ipr-notice#Legal_Disclaimer">liability</a>, <a href="https://www.w3.org/Consortium/Legal/ipr-notice#W3C_Trademarks">trademark</a> and <a href="https://www.w3.org/Consortium/Legal/2015/copyright-software-and-document">permissive document license</a> rules apply. </p>
   <hr title="Separator for header">
  </div>
  <div class="p-summary" data-fill-with="abstract">
   <h2 class="no-num no-toc no-ref heading settled" id="abstract"><span class="content">Abstract</span></h2>
   <p>This module introduces cascading variables as a new primitive value type that is accepted by all CSS properties, and custom properties for defining them.</p>
    <a href="https://www.w3.org/TR/CSS/">CSS</a> is a language for describing the rendering of structured documents
(such as HTML and XML)
on screen, on paper, etc. 
  </div>
  <h2 class="no-num no-toc no-ref heading settled" id="status"><span class="content">Status of this document</span></h2>
  <div data-fill-with="status">
   <p> This is a public copy of the editors’ draft.
	It is provided for discussion only and may change at any moment.
	Its publication here does not imply endorsement of its contents by W3C.
	Don’t cite this document other than as work in progress. </p>
   <p> <a href="https://github.com/w3c/csswg-drafts/issues">GitHub Issues</a> are preferred for discussion of this specification.
	When filing an issue, please put the text “css-variables” in the title,
	preferably like this:
	“[css-variables] <i data-lt>…summary of comment…</i>”.
	All issues and comments are <a href="https://lists.w3.org/Archives/Public/public-css-archive/">archived</a>,
	and there is also a <a href="https://lists.w3.org/Archives/Public/www-style/">historical archive</a>. </p>
   <p> This document was produced by the <a href="https://www.w3.org/Style/CSS/">CSS Working Group</a>. </p>
   <p> This document was produced by a group operating under
	the <a href="https://www.w3.org/Consortium/Patent-Policy/">W3C Patent Policy</a>.
	W3C maintains a <a href="https://www.w3.org/2004/01/pp-impl/32061/status" rel="disclosure">public list of any patent disclosures</a> made in connection with the deliverables of the group;
	that page also includes instructions for disclosing a patent.
	An individual who has actual knowledge of a patent which the individual believes contains <a href="https://www.w3.org/Consortium/Patent-Policy/#def-essential">Essential Claim(s)</a> must disclose the information in accordance with <a href="https://www.w3.org/Consortium/Patent-Policy/#sec-Disclosure">section 6 of the W3C Patent Policy</a>. </p>
   <p> This document is governed by the <a href="https://www.w3.org/2019/Process-20190301/" id="w3c_process_revision">1 March 2019 W3C Process Document</a>. </p>
   <p></p>
  </div>
  <div data-fill-with="at-risk"></div>
  <nav data-fill-with="table-of-contents" id="toc">
   <h2 class="no-num no-toc no-ref" id="contents">Table of Contents</h2>
   <ol class="toc" role="directory">
    <li><a href="#intro"><span class="secno">1</span> <span class="content"> Introduction</span></a>
    <li>
     <a href="#defining-variables"><span class="secno">2</span> <span class="content"> Defining Custom Properties: the <span class="property">--*</span> family of properties</span></a>
     <ol class="toc">
      <li><a href="#syntax"><span class="secno">2.1</span> <span class="content"> Custom Property Value Syntax</span></a>
      <li><a href="#guaranteed-invalid"><span class="secno">2.2</span> <span class="content"> Guaranteed-Invalid Values</span></a>
      <li><a href="#cycles"><span class="secno">2.3</span> <span class="content"> Resolving Dependency Cycles</span></a>
     </ol>
    <li>
     <a href="#using-variables"><span class="secno">3</span> <span class="content"> Using Cascading Variables: the <span class="css">var()</span> notation</span></a>
     <ol class="toc">
      <li><a href="#invalid-variables"><span class="secno">3.1</span> <span class="content"> Invalid Variables</span></a>
      <li><a href="#variables-in-shorthands"><span class="secno">3.2</span> <span class="content"> Variables in Shorthand Properties</span></a>
      <li><a href="#long-variables"><span class="secno">3.3</span> <span class="content"> Safely Handling Overly-Long Variables</span></a>
     </ol>
    <li>
     <a href="#apis"><span class="secno">4</span> <span class="content"> APIs</span></a>
     <ol class="toc">
      <li><a href="#serializing-custom-props"><span class="secno">4.1</span> <span class="content"> Serializing Custom Properties</span></a>
     </ol>
    <li>
     <a href="#changes"><span class="secno">5</span> <span class="content"> Changes</span></a>
     <ol class="toc">
      <li><a href="#changes-20151203"><span class="secno">5.1</span> <span class="content"> Changes Since the 03 December 2015 CR</span></a>
      <li><a href="#changes-20140506"><span class="secno">5.2</span> <span class="content"> Changes since the May 6 2014 Last Call Working Draft</span></a>
     </ol>
    <li><a href="#acks"><span class="secno">6</span> <span class="content"> Acknowledgments</span></a>
    <li><a href="#priv-sec"><span class="secno">7</span> <span class="content">Privacy and Security Considerations</span></a>
    <li>
     <a href="#conformance"><span class="secno"></span> <span class="content"> Conformance</span></a>
     <ol class="toc">
      <li><a href="#document-conventions"><span class="secno"></span> <span class="content"> Document conventions</span></a>
      <li><a href="#conform-classes"><span class="secno"></span> <span class="content"> Conformance classes</span></a>
      <li>
       <a href="#conform-responsible"><span class="secno"></span> <span class="content"> Requirements for Responsible Implementation of CSS</span></a>
       <ol class="toc">
        <li><a href="#conform-partial"><span class="secno"></span> <span class="content"> Partial Implementations</span></a>
        <li><a href="#conform-future-proofing"><span class="secno"></span> <span class="content"> Implementations of Unstable and Proprietary Features</span></a>
        <li><a href="#conform-testing"><span class="secno"></span> <span class="content"> Implementations of CR-level Features</span></a>
       </ol>
     </ol>
    <li>
     <a href="#index"><span class="secno"></span> <span class="content">Index</span></a>
     <ol class="toc">
      <li><a href="#index-defined-here"><span class="secno"></span> <span class="content">Terms defined by this specification</span></a>
      <li><a href="#index-defined-elsewhere"><span class="secno"></span> <span class="content">Terms defined by reference</span></a>
     </ol>
    <li>
     <a href="#references"><span class="secno"></span> <span class="content">References</span></a>
     <ol class="toc">
      <li><a href="#normative"><span class="secno"></span> <span class="content">Normative References</span></a>
      <li><a href="#informative"><span class="secno"></span> <span class="content">Informative References</span></a>
     </ol>
    <li><a href="#property-index"><span class="secno"></span> <span class="content">Property Index</span></a>
   </ol>
  </nav>
  <main>
   <h2 class="heading settled" data-level="1" id="intro"><span class="secno">1. </span><span class="content"> Introduction</span><a class="self-link" href="#intro"></a></h2>
   <p><em>This section is not normative.</em></p>
   <p>Large documents or applications
	(and even small ones)
	can contain quite a bit of CSS.
	Many of the values in the CSS file will be duplicate data;
	for example,
	a site may establish a color scheme
	and reuse three or four colors throughout the site.
	Altering this data can be difficult and error-prone,
	since it’s scattered throughout the CSS file
	(and possibly across multiple files),
	and may not be amenable to Find-and-Replace.</p>
   <p>This module introduces a family of custom author-defined properties known collectively as <a data-link-type="dfn" href="#custom-property" id="ref-for-custom-property">custom properties</a>,
	which allow an author to assign arbitrary values to a property with an author-chosen name,
	and the <a class="css" data-link-type="maybe" href="#funcdef-var" id="ref-for-funcdef-var">var()</a> function,
	which allow an author to then use those values in other properties elsewhere in the document.
	This makes it easier to read large files,
	as seemingly-arbitrary values now have informative names,
	and makes editing such files much easier and less error-prone,
	as one only has to change the value once,
	in the <span id="ref-for-custom-property①">custom property</span>,
	and the change will propagate to all uses of that variable automatically.</p>
   <h2 class="heading settled" data-level="2" id="defining-variables"><span class="secno">2. </span><span class="content"> Defining Custom Properties: the <a class="property" data-link-type="propdesc">--*</a> family of properties</span><a class="self-link" href="#defining-variables"></a></h2>
   <p>This specification defines an open-ended set of properties called <a data-link-type="dfn" href="#custom-property" id="ref-for-custom-property②">custom properties</a>,
	which, among other things, are used to define the <a data-link-type="dfn" href="#substitute-a-var" id="ref-for-substitute-a-var">substitution value</a> of <a class="css" data-link-type="maybe" href="#funcdef-var" id="ref-for-funcdef-var①">var()</a> functions.</p>
   <table class="def propdef" data-link-for-hint="--*">
    <tbody>
     <tr>
      <th>Name:
      <td><dfn class="css" data-dfn-type="property" data-export id="propdef-">--*<a class="self-link" href="#propdef-"></a></dfn>
     <tr class="value">
      <th><a href="https://drafts.csswg.org/css-values/#value-defs">Value:</a>
      <td class="prod"><a class="production css" data-link-type="type" href="https://drafts.csswg.org/css-syntax-3/#typedef-declaration-value" id="ref-for-typedef-declaration-value">&lt;declaration-value></a><a data-link-type="grammar" href="https://drafts.csswg.org/css-values-4/#mult-opt" id="ref-for-mult-opt">?</a> 
     <tr>
      <th><a href="https://drafts.csswg.org/css-cascade/#initial-values">Initial:</a>
      <td>the <a data-link-type="dfn" href="#guaranteed-invalid-value" id="ref-for-guaranteed-invalid-value">guaranteed-invalid value</a> 
     <tr>
      <th>Applies to:
      <td><a href="https://drafts.csswg.org/css-pseudo/#generated-content" title="Includes ::before and ::after pseudo-elements.">all elements</a> 
     <tr>
      <th><a href="https://drafts.csswg.org/css-cascade/#inherited-property">Inherited:</a>
      <td>yes 
     <tr>
      <th><a href="https://drafts.csswg.org/css-values/#percentages">Percentages:</a>
      <td>n/a 
     <tr>
      <th><a href="https://drafts.csswg.org/css-cascade/#computed">Computed value:</a>
      <td>specified value with variables substituted, or the <a data-link-type="dfn" href="#guaranteed-invalid-value" id="ref-for-guaranteed-invalid-value①">guaranteed-invalid value</a> 
     <tr>
      <th>Canonical order:
      <td>per grammar 
     <tr>
      <th><a href="https://drafts.csswg.org/web-animations/#animation-type">Animatable:</a>
      <td>no 
   </table>
   <p class="all-media">User Agents are expected to support this property on all media, including non-visual ones.</p>
   <p>A <dfn class="dfn-paneled" data-dfn-type="dfn" data-export id="custom-property">custom property</dfn> is any property
	whose name starts with two dashes (U+002D HYPHEN-MINUS),
	like <a class="property" data-link-type="propdesc">--foo</a>.
	The <dfn class="dfn-paneled css" data-dfn-type="type" data-export id="typedef-custom-property-name">&lt;custom-property-name></dfn> production corresponds to this:
	it’s defined as any valid <a data-link-type="dfn" href="https://drafts.csswg.org/css-syntax-3/#identifier" id="ref-for-identifier">identifier</a> that starts with two dashes,
	except <span class="css">--</span> itself,
	which is reserved for future use by CSS. <a data-link-type="dfn" href="#custom-property" id="ref-for-custom-property③">Custom properties</a> are solely for use by authors and users;
	CSS will never give them a meaning beyond what is presented here.</p>
   <div class="example" id="example-81b6bcdd">
    <a class="self-link" href="#example-81b6bcdd"></a> Custom properties define variables,
		referenced with the <a class="css" data-link-type="maybe" href="#funcdef-var" id="ref-for-funcdef-var②">var()</a> notation,
		which can be used for many purposes.
		For example, a page that consistently uses a small set of colors in its design
		can store the colors in custom properties
		and use them with variables: 
<pre class="highlight"><c- f>:root </c-><c- p>{</c->
  <c- k>--main-color</c-><c- p>:</c-> #06c<c- p>;</c->
  <c- k>--accent-color</c-><c- p>:</c-> #006<c- p>;</c->
<c- p>}</c->
<c- c>/* The rest of the CSS file */</c->
<c- f>#foo h1 </c-><c- p>{</c->
  <c- k>color</c-><c- p>:</c-> <c- nf>var</c-><c- p>(</c->--main-color<c- p>);</c->
<c- p>}</c->
</pre>
    <p>The naming provides a mnemonic for the colors,
		prevents difficult-to-spot typos in the color codes,
		and if the theme colors are ever changed,
		focuses the change on one simple spot
		(the custom property value)
		rather than requiring many edits across all stylesheets in the webpage.</p>
   </div>
   <p>Unlike other CSS properties,
	custom property names are <a data-link-type="dfn" href="https://html.spec.whatwg.org/multipage/infrastructure.html#case-sensitive" id="ref-for-case-sensitive">case-sensitive</a>.</p>
   <div class="example" id="example-ddbbde9e"><a class="self-link" href="#example-ddbbde9e"></a> While both <a class="property" data-link-type="propdesc">--foo</a> and --FOO are valid,
		they are distinct properties -
		using <span class="css">var(--foo)</span> will refer to the first one,
		while using <span class="css">var(--FOO)</span> will refer to the second. </div>
   <p>Custom properties are <strong>not</strong> reset by the <a class="property" data-link-type="propdesc" href="https://drafts.csswg.org/css-cascade-4/#propdef-all" id="ref-for-propdef-all">all</a> property. <span class="note">We may define a property in the future that resets all variables.</span></p>
   <p>The <a data-link-type="dfn" href="https://drafts.csswg.org/css-values-4/#css-wide-keywords" id="ref-for-css-wide-keywords">CSS-wide keywords</a> can be used in custom properties,
	with the same meaning as in any another property.</p>
   <p class="note" role="note"><span>Note:</span> That is, they’re interpreted at cascaded-value time as normal,
	and are not preserved as the custom property’s value,
	and thus are not substituted in by the corresponding variable.</p>
   <p class="note" role="note"><span>Note:</span> While this module focuses on the use of <a data-link-type="dfn" href="#custom-property" id="ref-for-custom-property④">custom properties</a> with the <a class="css" data-link-type="maybe" href="#funcdef-var" id="ref-for-funcdef-var③">var()</a> function to create “variables”,
	they can also be used as actual custom properties,
	parsed by and acted on by script.
	It’s expected that the CSS Extensions spec <a data-link-type="biblio" href="#biblio-css-extensions">[CSS-EXTENSIONS]</a> will expand on these use-cases and make them easier to do.</p>
   <p>Custom properties are ordinary properties,
	so they can be declared on any element,
	are resolved with the normal inheritance and cascade rules,
	can be made conditional with <a class="css" data-link-type="maybe" href="https://drafts.csswg.org/css-conditional-3/#at-ruledef-media" id="ref-for-at-ruledef-media">@media</a> and other conditional rules,
	can be used in HTML’s <code class="highlight">style</code> attribute,
	can be read or set using the CSSOM, etc.</p>
   <p>Notably, they can even be transitioned or animated,
	but since the UA has no way to interpret their contents,
	they always use the "flips at 50%" behavior
	that is used for any other pair of values that can’t be intelligently interpolated.
	However, any <a data-link-type="dfn" href="#custom-property" id="ref-for-custom-property⑤">custom property</a> used in a <a class="css" data-link-type="maybe" href="https://drafts.csswg.org/css-animations-1/#at-ruledef-keyframes" id="ref-for-at-ruledef-keyframes">@keyframes</a> rule
	becomes <dfn class="dfn-paneled" data-dfn-type="dfn" data-noexport id="animation-tainted">animation-tainted</dfn>,
	which affects how it is treated when referred to via the <a class="css" data-link-type="maybe" href="#funcdef-var" id="ref-for-funcdef-var④">var()</a> function in an animation property.</p>
   <div class="example" id="example-d6247b0f">
    <a class="self-link" href="#example-d6247b0f"></a> This style rule: 
<pre class="highlight"><c- f>:root </c-><c- p>{</c->
  <c- k>--header-color</c-><c- p>:</c-> #06c<c- p>;</c->
<c- p>}</c->
</pre>
    <p>declares a <a data-link-type="dfn" href="#custom-property" id="ref-for-custom-property⑥">custom property</a> named <a class="property" data-link-type="propdesc">--header-color</a> on the root element,
		and assigns to it the value "#06c".
		This property is then inherited to the elements in the rest of the document.
		Its value can be referenced with the <a class="css" data-link-type="maybe" href="#funcdef-var" id="ref-for-funcdef-var⑤">var()</a> function:</p>
<pre class="highlight"><c- f>h1 </c-><c- p>{</c-> <c- k>background-color</c-><c- p>:</c-> <c- nf>var</c-><c- p>(</c->--header-color<c- p>);</c-> <c- p>}</c->
</pre>
    <p>The preceding rule is equivalent to writing <a class="css" data-link-type="propdesc" href="https://drafts.csswg.org/css-backgrounds-3/#propdef-background-color" id="ref-for-propdef-background-color">background-color: #06c;</a>,
		except that the variable name makes the origin of the color clearer,
		and if <span class="css">var(--header-color)</span> is used on other elements in the document,
		all of the uses can be updated at once
		by changing the <a class="property" data-link-type="propdesc">--header-color</a> property on the root element.</p>
   </div>
   <div class="example" id="example-c3e4e8d9">
    <a class="self-link" href="#example-c3e4e8d9"></a> If a <a data-link-type="dfn" href="#custom-property" id="ref-for-custom-property⑦">custom property</a> is declared multiple times,
		the standard cascade rules help resolve it.
		Variables always draw from the computed value of the associated custom property on the same element: 
<pre class="highlight"><c- f>:root </c-><c- p>{</c-> <c- k>--color</c-><c- p>:</c-> blue<c- p>;</c-> <c- p>}</c->
<c- f>div </c-><c- p>{</c-> <c- k>--color</c-><c- p>:</c-> green<c- p>;</c-> <c- p>}</c->
<c- f>#alert </c-><c- p>{</c-> <c- k>--color</c-><c- p>:</c-> red<c- p>;</c-> <c- p>}</c->
<c- f>* </c-><c- p>{</c-> <c- k>color</c-><c- p>:</c-> <c- nf>var</c-><c- p>(</c->--color<c- p>);</c-> <c- p>}</c->

&lt;p><span style="color: blue">I inherited blue from the root element!</span>&lt;/p>
&lt;div><span style="color: green">I got green set directly on me!</span>&lt;/div>
&lt;div id='alert'>
  <span style="color: red">While I got red set directly on me!</span>
  &lt;p><span style="color: red">I’m red too, because of inheritance!</span>&lt;/p>
&lt;/div>
</pre>
   </div>
   <div class="example" id="example-658ebee9">
    <a class="self-link" href="#example-658ebee9"></a> A real-world example of <a data-link-type="dfn" href="#custom-property" id="ref-for-custom-property⑧">custom property</a> usage
		is easily separating out strings from where they’re used,
		to aid in maintenance of internationalization: 
<pre class="lang-css highlight"><c- f>:root,</c->
<c- f>:root:lang(en) </c-><c- p>{</c-><c- k>--external-link</c-><c- p>:</c-> <c- s>"external link"</c-><c- p>;}</c->
<c- f>:root:lang(de) </c-><c- p>{</c-><c- k>--external-link</c-><c- p>:</c-> <c- s>"externer Link"</c-><c- p>;}</c->

<c- f>a[href^="http"]::after </c-><c- p>{</c-><c- k>content</c-><c- p>:</c-> <c- s>" ("</c-> <c- nf>var</c-><c- p>(</c->--external-link<c- p>)</c-> <c- s>")"</c-><c- p>}</c->
</pre>
    <p>The variable declarations can even be kept in a separate file,
		to make maintaining the translations simpler.</p>
   </div>
   <h3 class="heading settled" data-level="2.1" id="syntax"><span class="secno">2.1. </span><span class="content"> Custom Property Value Syntax</span><a class="self-link" href="#syntax"></a></h3>
   <p>The allowed syntax for <a data-link-type="dfn" href="#custom-property" id="ref-for-custom-property⑨">custom properties</a> is extremely permissive.
	The <a class="production css" data-link-type="type" href="https://drafts.csswg.org/css-syntax-3/#typedef-declaration-value" id="ref-for-typedef-declaration-value①">&lt;declaration-value></a> production matches <em>any</em> sequence of one or more tokens,
	so long as the sequence does not contain <a class="production css" data-link-type="type" href="https://drafts.csswg.org/css-syntax-3/#typedef-bad-string-token" id="ref-for-typedef-bad-string-token">&lt;bad-string-token></a>, <a class="production css" data-link-type="type" href="https://drafts.csswg.org/css-syntax-3/#typedef-bad-url-token" id="ref-for-typedef-bad-url-token">&lt;bad-url-token></a>,
	unmatched <a class="production css" data-link-type="type" href="https://drafts.csswg.org/css-syntax-3/#tokendef-close-paren" id="ref-for-tokendef-close-paren">&lt;)-token></a>, <a class="production css" data-link-type="type" href="https://drafts.csswg.org/css-syntax-3/#tokendef-close-square" id="ref-for-tokendef-close-square">&lt;]-token></a>, or <a class="production css" data-link-type="type" href="https://drafts.csswg.org/css-syntax-3/#tokendef-close-curly" id="ref-for-tokendef-close-curly">&lt;}-token></a>,
	or top-level <a class="production css" data-link-type="type" href="https://drafts.csswg.org/css-syntax-3/#typedef-semicolon-token" id="ref-for-typedef-semicolon-token">&lt;semicolon-token></a> tokens or <a class="production css" data-link-type="type" href="https://drafts.csswg.org/css-syntax-3/#typedef-delim-token" id="ref-for-typedef-delim-token">&lt;delim-token></a> tokens with a value of "!".</p>
   <p>In addition, if the value of a <a data-link-type="dfn" href="#custom-property" id="ref-for-custom-property①⓪">custom property</a> contains a <a class="css" data-link-type="maybe" href="#funcdef-var" id="ref-for-funcdef-var⑥">var()</a> reference,
	the <span class="css" id="ref-for-funcdef-var⑦">var()</span> reference must be valid according to the specified <span class="css" id="ref-for-funcdef-var⑧">var()</span> grammar.
	If not, the <span id="ref-for-custom-property①①">custom property</span> is invalid and must be ignored.</p>
   <p class="note" role="note"><span>Note:</span> This definition,
	along with the general CSS syntax rules,
	implies that a custom property value never includes an unmatched quote or bracket,
	and so cannot have any effect on larger syntax constructs,
	like the enclosing style rule,
	when reserialized.</p>
   <p class="note" role="note"><span>Note:</span> Custom properties can contain a trailing <span class="css">!important</span>,
	but this is automatically removed from the property’s value by the CSS parser,
	and makes the custom property "important" in the CSS cascade.
	In other words, the prohibition on top-level "!" characters
	does not prevent <span class="css">!important</span> from being used,
	as the <span class="css">!important</span> is removed before syntax checking happens.</p>
   <div class="example" id="example-fb41560d">
    <a class="self-link" href="#example-fb41560d"></a> For example, the following is a valid custom property: 
<pre class="highlight">--foo: if(x > 5) this.width = 10;
</pre>
    <p>While this value is obviously useless as a <em>variable</em>,
		as it would be invalid in any normal property,
		it might be read and acted on by JavaScript.</p>
   </div>
   <p>The values of custom properties,
	and the values of <a class="css" data-link-type="maybe" href="#funcdef-var" id="ref-for-funcdef-var⑨">var()</a> functions substituted into custom properties,
	are <em>case-sensitive</em>,
	and must be preserved in their original author-given casing.
	(Many CSS values are <a data-link-type="dfn" href="https://infra.spec.whatwg.org/#ascii-case-insensitive" id="ref-for-ascii-case-insensitive">ASCII case-insensitive</a>,
	which user agents can take advantage of by "canonicalizing" them into a single casing,
	but that isn’t allowed for custom properties.)</p>
   <h3 class="heading settled" data-level="2.2" id="guaranteed-invalid"><span class="secno">2.2. </span><span class="content"> Guaranteed-Invalid Values</span><a class="self-link" href="#guaranteed-invalid"></a></h3>
   <p>The initial value of a <a data-link-type="dfn" href="#custom-property" id="ref-for-custom-property①②">custom property</a> is a <dfn class="dfn-paneled" data-dfn-type="dfn" data-export id="guaranteed-invalid-value">guaranteed-invalid value</dfn>.
	As defined in <a href="#using-variables">§ 3 Using Cascading Variables: the var() notation</a>,
	using <a class="css" data-link-type="maybe" href="#funcdef-var" id="ref-for-funcdef-var①⓪">var()</a> to substitute a <span id="ref-for-custom-property①③">custom property</span> with this as its value
	makes the property referencing it <a data-link-type="dfn" href="#invalid-at-computed-value-time" id="ref-for-invalid-at-computed-value-time">invalid at computed-value time</a>.</p>
   <p>This value serializes as the empty string,
	but actually writing an empty value into a custom property,
	like <span style=";white-space:nowrap"><a class="css" data-link-type="propdesc">--foo: ;</a></span>,
	is a valid (empty) value,
	not the <a data-link-type="dfn" href="#guaranteed-invalid-value" id="ref-for-guaranteed-invalid-value②">guaranteed-invalid value</a>.
	If, for whatever reason,
	one wants to manually reset a variable to the <span id="ref-for-guaranteed-invalid-value③">guaranteed-invalid value</span>,
	using the keyword <a class="css" data-link-type="maybe" href="https://drafts.csswg.org/css-cascade-4/#valdef-all-initial" id="ref-for-valdef-all-initial">initial</a> will do this.</p>
   <h3 class="heading settled" data-level="2.3" id="cycles"><span class="secno">2.3. </span><span class="content"> Resolving Dependency Cycles</span><a class="self-link" href="#cycles"></a></h3>
   <p><a data-link-type="dfn" href="#custom-property" id="ref-for-custom-property①④">Custom properties</a> are left almost entirely unevaluated,
	except that they allow and evaluate the <a class="css" data-link-type="maybe" href="#funcdef-var" id="ref-for-funcdef-var①①">var()</a> function in their value.
	This can create cyclic dependencies
	where a custom property uses a <span class="css" id="ref-for-funcdef-var①②">var()</span> referring to itself,
	or two or more <span id="ref-for-custom-property①⑤">custom properties</span> each attempt to refer to each other.</p>
   <p>For each element,
	create a directed dependency graph,
	containing nodes for each <a data-link-type="dfn" href="#custom-property" id="ref-for-custom-property①⑥">custom property</a>.
	If the value of a <span id="ref-for-custom-property①⑦">custom property</span> <var>prop</var> contains a <a class="css" data-link-type="maybe" href="#funcdef-var" id="ref-for-funcdef-var①③">var()</a> function referring to the property <var>var</var> (including in the fallback argument of <span class="css" id="ref-for-funcdef-var①④">var()</span>),
	add an edge between <var>prop</var> and the <var>var</var>. <span class="note">Edges are possible from a custom property to itself.</span></p>
   <p>If there is a cycle in the dependency graph,
	all the <a data-link-type="dfn" href="#custom-property" id="ref-for-custom-property①⑧">custom properties</a> in the cycle
	are <dfn class="dfn-paneled" data-dfn-type="dfn" data-export id="cyclic-at-computed-value-time">cyclic at computed-value time</dfn>,
	and must compute to the <a data-link-type="dfn" href="#guaranteed-invalid-value" id="ref-for-guaranteed-invalid-value④">guaranteed-invalid value</a>.</p>
   <p class="note" role="note"><span>Note:</span> Defined properties that participate in a dependency cycle
	either end up with invalid variables in their value
	(becoming <a data-link-type="dfn" href="#invalid-at-computed-value-time" id="ref-for-invalid-at-computed-value-time①">invalid at computed-value time</a>),
	or define their own cyclic handling
	(like <a class="property" data-link-type="propdesc" href="https://drafts.csswg.org/css-fonts-3/#propdef-font-size" id="ref-for-propdef-font-size">font-size</a> using <a class="css" data-link-type="maybe" href="https://drafts.csswg.org/css-values-4/#em" id="ref-for-em">em</a> values).
	They do not computed to the <a data-link-type="dfn" href="#guaranteed-invalid-value" id="ref-for-guaranteed-invalid-value⑤">guaranteed-invalid value</a> like custom properties do.</p>
   <div class="example" id="example-75bf73fb">
    <a class="self-link" href="#example-75bf73fb"></a> This example shows a custom property safely using a variable: 
<pre class="highlight"><c- f>:root </c-><c- p>{</c->
  <c- k>--main-color</c-><c- p>:</c-> #c06<c- p>;</c->
  <c- k>--accent-background</c-><c- p>:</c-> <c- nf>linear-gradient</c-><c- p>(</c->to top<c- p>,</c-> <c- nf>var</c-><c- p>(</c->--main-color<c- p>),</c-> white<c- p>);</c->
<c- p>}</c->
</pre>
    <p>The <a class="property" data-link-type="propdesc">--accent-background</a> property
		(along with any other properties that use <span class="css">var(--main-color)</span>)
		will automatically update when the <span class="property">--main-color</span> property is changed.</p>
   </div>
   <div class="example invalid-example" id="example-606d24c9">
    <a class="self-link" href="#example-606d24c9"></a> On the other hand,
		this example shows an invalid instance of variables depending on each other: 
<pre class="highlight"><c- f>:root </c-><c- p>{</c->
  <c- k>--one</c-><c- p>:</c-> <c- nf>calc</c-><c- p>(</c-><c- nf>var</c-><c- p>(</c->--two<c- p>)</c-> + 20px);
  --two: calc(var(--one) - 20px);
}
</pre>
    <p>Both <a class="property" data-link-type="propdesc">--one</a> and <span class="property">--two</span> are now <a data-link-type="dfn" href="#cyclic-at-computed-value-time" id="ref-for-cyclic-at-computed-value-time">cyclic at computed-value time</a>,
		and compute to the <a data-link-type="dfn" href="#guaranteed-invalid-value" id="ref-for-guaranteed-invalid-value⑥">guaranteed-invalid value</a> rather than than lengths.</p>
   </div>
   <p>It is important to note that <a data-link-type="dfn" href="#custom-property" id="ref-for-custom-property①⑨">custom properties</a> resolve any <a class="css" data-link-type="maybe" href="#funcdef-var" id="ref-for-funcdef-var①⑤">var()</a> functions in their values at computed-value time,
	which occurs <em>before</em> the value is inherited.
	In general,
	cyclic dependencies occur only when multiple custom properties on the same element refer to each other;
	custom properties defined on elements higher in the element tree can never cause a cyclic reference with properties defined on elements lower in the element tree.</p>
   <div class="example" id="example-beef67cd">
    <a class="self-link" href="#example-beef67cd"></a> For example,
		given the following structure,
		these custom properties are <strong>not</strong> cyclic,
		and all define valid variables: 
<pre class="highlight"><c- p>&lt;</c-><c- f>one</c-><c- p>>&lt;</c-><c- f>two</c-><c- p>>&lt;</c-><c- f>three</c-> <c- p>/>&lt;/</c-><c- f>two</c-><c- p>>&lt;/</c-><c- f>one</c-><c- p>></c->
<c- p>&lt;</c-><c- f>style</c-><c- p>></c->
<c- f>one</c->   <c- p>{</c-> --<c- n>foo</c-><c- p>:</c-> <c- mi>10</c-><c- b>px</c-><c- p>;</c-> <c- p>}</c->
<c- f>two</c->   <c- p>{</c-> --<c- n>bar</c-><c- p>:</c-> calc<c- p>(</c-><c- nf>var</c-><c- p>(</c-><c- o>--</c-><c- n>foo</c-><c- p>)</c-> <c- o>+</c-> <c- mi>10</c-><c- b>px</c-><c- p>);</c-> <c- p>}</c->
<c- f>three</c-> <c- p>{</c-> --<c- n>foo</c-><c- p>:</c-> calc<c- p>(</c-><c- nf>var</c-><c- p>(</c-><c- o>--</c-><c- n>bar</c-><c- p>)</c-> <c- o>+</c-> <c- mi>10</c-><c- b>px</c-><c- p>);</c-> <c- p>}</c->
<c- p>&lt;/</c-><c- f>style</c-><c- p>></c->
</pre>
    <p>The &lt;one> element defines a value for <a class="property" data-link-type="propdesc">--foo</a>.
		The &lt;two> element inherits this value,
		and additionally assigns a value to <span class="property">--bar</span> using the <span class="css">foo</span> variable.
		Finally,
		the &lt;three> element inherits the <span class="property">--bar</span> value <em>after</em> variable substitution
		(in other words, it sees the value <span class="css">calc(10px + 10px)</span>),
		and then redefines <span class="property">--foo</span> in terms of that value.
		Since the value it inherited for <span class="property">--bar</span> no longer contains a reference to the <span class="property">--foo</span> property defined on &lt;one>,
		defining <span class="property">--foo</span> using the <span class="css">var(--bar)</span> variable is not cyclic,
		and actually defines a value that will eventually
		(when referenced as a variable in a normal property)
		resolve to <span class="css">30px</span>.</p>
   </div>
   <h2 class="heading settled" data-level="3" id="using-variables"><span class="secno">3. </span><span class="content"> Using Cascading Variables: the <a class="css" data-link-type="maybe" href="#funcdef-var" id="ref-for-funcdef-var①⑥">var()</a> notation</span><a class="self-link" href="#using-variables"></a></h2>
   <p>The value of a <a data-link-type="dfn" href="#custom-property" id="ref-for-custom-property②⓪">custom property</a> can be substituted into the value of another property
	with the <a class="css" data-link-type="maybe" href="#funcdef-var" id="ref-for-funcdef-var①⑦">var()</a> function.
	The syntax of <span class="css" id="ref-for-funcdef-var①⑧">var()</span> is:</p>
<pre class="prod highlight"><dfn class="dfn-paneled" data-dfn-type="function" data-export id="funcdef-var">var()</dfn> = var( <a class="production" data-link-type="type" href="#typedef-custom-property-name" id="ref-for-typedef-custom-property-name">&lt;custom-property-name></a> <a data-link-type="grammar" href="https://drafts.csswg.org/css-values-4/#comb-comma" id="ref-for-comb-comma">,</a> <a class="production" data-link-type="type" href="https://drafts.csswg.org/css-syntax-3/#typedef-declaration-value" id="ref-for-typedef-declaration-value②">&lt;declaration-value></a><a data-link-type="grammar" href="https://drafts.csswg.org/css-values-4/#mult-opt" id="ref-for-mult-opt①">?</a> )
</pre>
   <p>The <a class="css" data-link-type="maybe" href="#funcdef-var" id="ref-for-funcdef-var①⑨">var()</a> function can be used in place of any part of a value in any property on an element.
	The <span class="css" id="ref-for-funcdef-var②⓪">var()</span> function can not be used as
	property names,
	selectors,
	or anything else besides property values.
	(Doing so usually produces invalid syntax,
	or else a value whose meaning has no connection to the variable.)</p>
   <div class="example" id="example-43a8c543">
    <a class="self-link" href="#example-43a8c543"></a> For example, the following code incorrectly attempts to use a variable as a property name: 
<pre class="highlight"><c- f>.foo </c-><c- p>{</c->
  <c- k>--side</c-><c- p>:</c-> margin-top<c- p>;</c->
  <c- nf>var</c-><c- p>(</c->--side<c- p>)</c->: 20px;
}
</pre>
    <p>This is <em>not</em> equivalent to setting <a class="css" data-link-type="propdesc" href="https://drafts.csswg.org/css-box-3/#propdef-margin-top" id="ref-for-propdef-margin-top">margin-top: 20px;</a>.
		Instead, the second declaration is simply thrown away as a syntax error
		for having an invalid property name.</p>
   </div>
   <p>The first argument to the function is the name of the <a data-link-type="dfn" href="#custom-property" id="ref-for-custom-property②①">custom property</a> to be substituted.
	The second argument to the function, if provided,
	is a fallback value,
	which is used as the substitution value when the value of the referenced <span id="ref-for-custom-property②②">custom property</span> is the <a data-link-type="dfn" href="#guaranteed-invalid-value" id="ref-for-guaranteed-invalid-value⑦">guaranteed-invalid value</a>.</p>
   <p class="note" role="note"><span>Note:</span> The syntax of the fallback, like that of <a data-link-type="dfn" href="#custom-property" id="ref-for-custom-property②③">custom properties</a>, allows commas.
	For example, <span class="css">var(--foo, red, blue)</span> defines a fallback of <span class="css">red, blue</span>;
	that is, anything between the first comma and the end of the function is considered a fallback value.</p>
   <div class="example" id="example-abd63bac">
    <a class="self-link" href="#example-abd63bac"></a> The fallback value allows for some types of defensive coding.
		For example,
		an author may create a component
		intended to be included in a larger application,
		and use variables to style it
		so that it’s easy for the author of the larger application
		to theme the component to match the rest of the app. 
    <p>Without fallback,
		the app author must supply a value for every variable that your component uses.
		With fallback, the component author can supply defaults,
		so the app author only needs to supply values for the variables they wish to override.</p>
<pre class="highlight"><c- c>/* In the component’s style: */</c->
<c- f>.component .header </c-><c- p>{</c->
  <c- k>color</c-><c- p>:</c-> <c- nf>var</c-><c- p>(</c->--header-color<c- p>,</c-> blue<c- p>);</c->
<c- p>}</c->
<c- f>.component .text </c-><c- p>{</c->
  <c- k>color</c-><c- p>:</c-> <c- nf>var</c-><c- p>(</c->--text-color<c- p>,</c-> black<c- p>);</c->
<c- p>}</c->

<c- c>/* In the larger application’s style: */</c->
<c- f>.component </c-><c- p>{</c->
  <c- k>--text-color</c-><c- p>:</c-> #080<c- p>;</c->
  <c- c>/* header-color isn’t set,</c->
<c- c>     and so remains blue,</c->
<c- c>     the fallback value */</c->
<c- p>}</c->
</pre>
   </div>
   <p>If a property contains one or more <a class="css" data-link-type="maybe" href="#funcdef-var" id="ref-for-funcdef-var②①">var()</a> functions,
	and those functions are syntactically valid,
	the entire property’s grammar must be assumed to be valid at parse time.
	It is only syntax-checked at computed-value time,
	after <span class="css" id="ref-for-funcdef-var②②">var()</span> functions have been <a data-link-type="dfn" href="#substitute-a-var" id="ref-for-substitute-a-var①">substituted</a>.</p>
   <p>To <dfn class="dfn-paneled" data-dfn-type="dfn" data-export data-lt="substitute a var()|var() substitution" id="substitute-a-var">substitute a var()</dfn> in a property’s value:</p>
   <ol>
    <li>
      If the <a data-link-type="dfn" href="#custom-property" id="ref-for-custom-property②④">custom property</a> named by the first argument to the <a class="css" data-link-type="maybe" href="#funcdef-var" id="ref-for-funcdef-var②③">var()</a> function is <a data-link-type="dfn" href="#animation-tainted" id="ref-for-animation-tainted">animation-tainted</a>,
			and the <span class="css" id="ref-for-funcdef-var②④">var()</span> function is being used in: 
     <ul>
      <li data-md>
       <p>the <a class="property" data-link-type="propdesc" href="https://drafts.csswg.org/css-animations-1/#propdef-animation" id="ref-for-propdef-animation">animation</a> property or one of its longhands,</p>
      <li data-md>
       <p>the <a class="property" data-link-type="propdesc" href="https://drafts.csswg.org/css-display-3/#propdef-display" id="ref-for-propdef-display">display</a> property, such that after substitution the property would have a value that suppresses the element’s box (such as <a class="css" data-link-type="maybe" href="https://drafts.csswg.org/css-display-3/#valdef-display-none" id="ref-for-valdef-display-none">none</a> or <a class="css" data-link-type="maybe" href="https://drafts.csswg.org/css-display-3/#valdef-display-contents" id="ref-for-valdef-display-contents">contents</a>)</p>
     </ul>
     <p>treat the <a data-link-type="dfn" href="#custom-property" id="ref-for-custom-property②⑤">custom property</a> as having its initial value for the rest of this algorithm.</p>
    <li> If the value of the <a data-link-type="dfn" href="#custom-property" id="ref-for-custom-property②⑥">custom property</a> named by the first argument to the <a class="css" data-link-type="maybe" href="#funcdef-var" id="ref-for-funcdef-var②⑤">var()</a> function
			is anything but the initial value,
			replace the <span class="css" id="ref-for-funcdef-var②⑥">var()</span> function by the value of the corresponding <span id="ref-for-custom-property②⑦">custom property</span>. 
    <li> Otherwise, if the <a class="css" data-link-type="maybe" href="#funcdef-var" id="ref-for-funcdef-var②⑦">var()</a> function has a fallback value as its second argument,
			replace the <span class="css" id="ref-for-funcdef-var②⑧">var()</span> function by the fallback value.
			If there are any <span class="css" id="ref-for-funcdef-var②⑨">var()</span> references in the fallback, <a data-link-type="dfn" href="#substitute-a-var" id="ref-for-substitute-a-var②">substitute</a> them as well. 
    <li>
      Otherwise,
			the property containing the <a class="css" data-link-type="maybe" href="#funcdef-var" id="ref-for-funcdef-var③⓪">var()</a> function is <a data-link-type="dfn" href="#invalid-at-computed-value-time" id="ref-for-invalid-at-computed-value-time②">invalid at computed-value time</a>. 
     <p class="note" role="note"><span>Note:</span> Other things can also make a property <a data-link-type="dfn" href="#invalid-at-computed-value-time" id="ref-for-invalid-at-computed-value-time③">invalid at computed-value time</a>.</p>
   </ol>
   <div class="note" role="note">
     Note that <a data-link-type="dfn" href="#substitute-a-var" id="ref-for-substitute-a-var③">var() substitution</a> takes place at the level of CSS tokens <a data-link-type="biblio" href="#biblio-css-syntax-3">[css-syntax-3]</a>,
		not at a textual level;
		you can’t build up a single token where part of it is provided by a variable: 
<pre class="highlight"><c- f>.foo </c-><c- p>{</c->
  <c- k>--gap</c-><c- p>:</c-> <c- m>20</c-><c- p>;</c->
  <c- k>margin-top</c-><c- p>:</c-> <c- nf>var</c-><c- p>(</c->--gap<c- p>)</c->px<c- p>;</c->
<c- p>}</c->
</pre>
    <p>This is <em>not</em> equivalent to setting <a class="css" data-link-type="propdesc" href="https://drafts.csswg.org/css-box-3/#propdef-margin-top" id="ref-for-propdef-margin-top①">margin-top: 20px;</a> (a length).
		Instead, it’s equivalent to <span class="css" id="ref-for-propdef-margin-top②">margin-top: 20 px;</span> (a number followed by an ident),
		which is simply an invalid value for the <span class="property" id="ref-for-propdef-margin-top③">margin-top</span> property.
		Note, though, that <a class="css" data-link-type="maybe" href="https://drafts.csswg.org/css-values-4/#funcdef-calc" id="ref-for-funcdef-calc">calc()</a> can be used to validly achieve the same thing, like so:</p>
<pre class="highlight"><c- f>.foo </c-><c- p>{</c->
  <c- k>--gap</c-><c- p>:</c-> <c- m>20</c-><c- p>;</c->
  <c- k>margin-top</c-><c- p>:</c-> <c- nf>calc</c-><c- p>(</c-><c- nf>var</c-><c- p>(</c->--gap<c- p>)</c-> * 1px);
}
</pre>
   </div>
   <p><a class="css" data-link-type="maybe" href="#funcdef-var" id="ref-for-funcdef-var③①">var()</a> functions are <a data-link-type="dfn" href="#substitute-a-var" id="ref-for-substitute-a-var④">substituted</a> at computed-value time.
	If a declaration,
	once all <span class="css" id="ref-for-funcdef-var③②">var()</span> functions are substituted in,
	does not match its declared grammar,
	the declaration is <a data-link-type="dfn" href="#invalid-at-computed-value-time" id="ref-for-invalid-at-computed-value-time④">invalid at computed-value time</a>.</p>
   <div class="example" id="example-6ec8308f">
    <a class="self-link" href="#example-6ec8308f"></a> For example,
		the following usage is fine from a syntax standpoint,
		but results in nonsense when the variable is substituted in: 
<pre class="highlight"><c- f>:root </c-><c- p>{</c-> <c- k>--looks-valid</c-><c- p>:</c-> <c- m>20</c-><c- l>px</c-><c- p>;</c-> <c- p>}</c->
<c- f>p </c-><c- p>{</c-> <c- k>background-color</c-><c- p>:</c-> <c- nf>var</c-><c- p>(</c->--looks-valid<c- p>);</c-> <c- p>}</c->
</pre>
    <p>Since <span class="css">20px</span> is an invalid value for <a class="property" data-link-type="propdesc" href="https://drafts.csswg.org/css-backgrounds-3/#propdef-background-color" id="ref-for-propdef-background-color①">background-color</a>,
		this instance of the property computes to <a class="css" data-link-type="maybe" href="https://drafts.csswg.org/css-color-4/#valdef-color-transparent" id="ref-for-valdef-color-transparent">transparent</a> (the initial value for <span class="property" id="ref-for-propdef-background-color②">background-color</span>)
		instead.</p>
    <p>If the property was one that’s inherited by default,
		such as <a class="property css" data-link-type="property" href="https://drafts.csswg.org/css-color-4/#propdef-color" id="ref-for-propdef-color">color</a>,
		it would compute to the inherited value
		rather than the initial value.</p>
   </div>
   <h3 class="heading settled" data-level="3.1" id="invalid-variables"><span class="secno">3.1. </span><span class="content"> Invalid Variables</span><a class="self-link" href="#invalid-variables"></a></h3>
   <p>When a <a data-link-type="dfn" href="#custom-property" id="ref-for-custom-property②⑧">custom property’s</a> value is the <a data-link-type="dfn" href="#guaranteed-invalid-value" id="ref-for-guaranteed-invalid-value⑧">guaranteed-invalid value</a>, <a class="css" data-link-type="maybe" href="#funcdef-var" id="ref-for-funcdef-var③③">var()</a> functions cannot use it for substitution.
	Attempting to do so
	makes the declaration <a data-link-type="dfn" href="#invalid-at-computed-value-time" id="ref-for-invalid-at-computed-value-time⑤">invalid at computed-value time</a>,
	unless a valid fallback is specified.</p>
   <p>A declaration can be <dfn class="dfn-paneled" data-dfn-type="dfn" data-export id="invalid-at-computed-value-time">invalid at computed-value time</dfn> if it contains a <a class="css" data-link-type="maybe" href="#funcdef-var" id="ref-for-funcdef-var③④">var()</a> that references a <a data-link-type="dfn" href="#custom-property" id="ref-for-custom-property②⑨">custom property</a> with the <a data-link-type="dfn" href="#guaranteed-invalid-value" id="ref-for-guaranteed-invalid-value⑨">guaranteed-invalid value</a>,
	as explained above,
	or if it uses a valid <span id="ref-for-custom-property③⓪">custom property</span>,
	but the property value,
	after substituting its <span class="css" id="ref-for-funcdef-var③⑤">var()</span> functions,
	is invalid.
	When this happens,
	the computed value of the property is either
	the property’s inherited value
	or its initial value
	depending on whether the property is inherited or not, respectively,
	as if the property’s value had been specified as the <a class="css" data-link-type="maybe" href="https://drafts.csswg.org/css-cascade-4/#valdef-all-unset" id="ref-for-valdef-all-unset">unset</a> keyword.</p>
   <div class="example" id="example-53e4f9d5">
    <a class="self-link" href="#example-53e4f9d5"></a> For example, in the following code: 
<pre class="highlight"><c- f>:root </c-><c- p>{</c-> <c- k>--not-a-color</c-><c- p>:</c-> <c- m>20</c-><c- l>px</c-><c- p>;</c-> <c- p>}</c->
<c- f>p </c-><c- p>{</c-> <c- k>background-color</c-><c- p>:</c-> red<c- p>;</c-> <c- p>}</c->
<c- f>p </c-><c- p>{</c-> <c- k>background-color</c-><c- p>:</c-> <c- nf>var</c-><c- p>(</c->--not-a-color<c- p>);</c-> <c- p>}</c->
</pre>
    <p>the &lt;p> elements will have transparent backgrounds
		(the initial value for <a class="property" data-link-type="propdesc" href="https://drafts.csswg.org/css-backgrounds-3/#propdef-background-color" id="ref-for-propdef-background-color③">background-color</a>),
		rather than red backgrounds.
		The same would happen if the <a data-link-type="dfn" href="#custom-property" id="ref-for-custom-property③①">custom property</a> itself was unset,
		or contained an invalid <a class="css" data-link-type="maybe" href="#funcdef-var" id="ref-for-funcdef-var③⑥">var()</a> function.</p>
    <p>Note the difference between this
		and what happens if the author had just written <a class="css" data-link-type="propdesc" href="https://drafts.csswg.org/css-backgrounds-3/#propdef-background-color" id="ref-for-propdef-background-color④">background-color: 20px</a> directly in their stylesheet -
		that would be a normal syntax error,
		which would cause the rule to be discarded,
		so the <span class="css" id="ref-for-propdef-background-color⑤">background-color: red</span> rule would be used instead.</p>
   </div>
   <p class="note" role="note"><span>Note:</span> The <a data-link-type="dfn" href="#invalid-at-computed-value-time" id="ref-for-invalid-at-computed-value-time⑥">invalid at computed-value time</a> concept exists
	because variables can’t "fail early" like other syntax errors can,
	so by the time the user agent realizes a property value is invalid,
	it’s already thrown away the other cascaded values.</p>
   <h3 class="heading settled" data-level="3.2" id="variables-in-shorthands"><span class="secno">3.2. </span><span class="content"> Variables in Shorthand Properties</span><a class="self-link" href="#variables-in-shorthands"></a></h3>
   <p>The use of <a class="css" data-link-type="maybe" href="#funcdef-var" id="ref-for-funcdef-var③⑦">var()</a> functions in <a data-link-type="dfn" href="https://drafts.csswg.org/css-cascade-4/#shorthand-property" id="ref-for-shorthand-property">shorthand properties</a> presents some unique difficulties.</p>
   <p>For non-custom properties,
	the value of a shorthand property is separated out into its component <a data-link-type="dfn" href="https://drafts.csswg.org/css-cascade-4/#longhand" id="ref-for-longhand">longhand properties</a> at parse time,
	and then the longhands themselves participate in the <a data-link-type="dfn" href="https://drafts.csswg.org/css-cascade-4/#cascade" id="ref-for-cascade">cascade</a>,
	with the shorthand more-or-less discarded.
	If a <a class="css" data-link-type="maybe" href="#funcdef-var" id="ref-for-funcdef-var③⑧">var()</a> functions is used in a shorthand, however,
	one can’t tell what values are meant to go where;
	it may in fact be impossible to separate it out at parse time,
	as a single <span class="css" id="ref-for-funcdef-var③⑨">var()</span> function may substitute in the value of several longhands at once.</p>
   <p>To get around this,
	implementations must fill in longhands with a special, unobservable-to-authors <dfn class="dfn-paneled" data-dfn-type="dfn" data-export id="pending-substitution-value">pending-substitution value</dfn> that indicates the shorthand contains a variable,
	and thus the longhand’s value is pending variable substitution.
	This value must then be cascaded as normal,
	and at computed-value time,
	after <a class="css" data-link-type="maybe" href="#funcdef-var" id="ref-for-funcdef-var④⓪">var()</a> functions are finally substituted in,
	the shorthand must be parsed and the longhands must be given their appropriate values at that point.</p>
   <p><a data-link-type="dfn" href="#pending-substitution-value" id="ref-for-pending-substitution-value">Pending-substitution values</a> must be serialized as the empty string,
	if an API allows them to be observed.</p>
   <p>Similarly,
	while <a data-link-type="biblio" href="#biblio-cssom">[CSSOM]</a> defines that shorthand properties are serialized
	by appropriately concatenating the values of their corresponding longhands,
	shorthands that are specified with explicit <a class="css" data-link-type="maybe" href="#funcdef-var" id="ref-for-funcdef-var④①">var()</a> functions
	must serialize to the original, <span class="css" id="ref-for-funcdef-var④②">var()</span>-containing value.
	For other shorthands,
	if any of the longhand subproperties for that shorthand have <a data-link-type="dfn" href="#pending-substitution-value" id="ref-for-pending-substitution-value①">pending-substitution values</a> then the serialized value of the shorthand must be the empty string.</p>
   <h3 class="heading settled" data-level="3.3" id="long-variables"><span class="secno">3.3. </span><span class="content"> Safely Handling Overly-Long Variables</span><a class="self-link" href="#long-variables"></a></h3>
   <p>Naively implemented, <a class="css" data-link-type="maybe" href="#funcdef-var" id="ref-for-funcdef-var④③">var()</a> functions can be used in a variation of the "billion laughs attack":</p>
   <div class="example" id="example-9c9258de">
    <a class="self-link" href="#example-9c9258de"></a> 
<pre class="highlight" lang="css"><c- f>.foo </c-><c- p>{</c->
  <c- k>--prop1</c-><c- p>:</c-> lol<c- p>;</c->
  <c- k>--prop2</c-><c- p>:</c-> <c- nf>var</c-><c- p>(</c->--prop1<c- p>)</c-> <c- nf>var</c-><c- p>(</c->--prop1<c- p>);</c->
  <c- k>--prop3</c-><c- p>:</c-> <c- nf>var</c-><c- p>(</c->--prop2<c- p>)</c-> <c- nf>var</c-><c- p>(</c->--prop2<c- p>);</c->
  <c- k>--prop4</c-><c- p>:</c-> <c- nf>var</c-><c- p>(</c->--prop3<c- p>)</c-> <c- nf>var</c-><c- p>(</c->--prop3<c- p>);</c->
  <c- c>/* etc */</c->
<c- p>}</c->
</pre>
    <p>In this short example, <span class="css">--prop4</span>’s computed value is <span class="css">lol lol lol lol lol lol lol lol</span>,
		containing 8 copies of the original <span class="css">lol</span>.
		Every additional level added to this doubles the number of identifiers;
		extending it to a mere 30 levels,
		the work of a few minutes by hand,
		would make <span class="css">--prop30</span> contain <em>nearly a billion instances</em> of the identifier.</p>
   </div>
   <p>To avoid this sort of attack,
	UAs must impose a UA-defined limit on the allowed length of the token stream
	that a <a class="css" data-link-type="maybe" href="#funcdef-var" id="ref-for-funcdef-var④④">var()</a> function expands into.
	If a <span class="css" id="ref-for-funcdef-var④⑤">var()</span> would expand into a longer token stream than this limit,
	it instead makes the property it’s expanding into <a data-link-type="dfn" href="#invalid-at-computed-value-time" id="ref-for-invalid-at-computed-value-time⑦">invalid at computed-value time</a>.</p>
   <p>This specification does not define what size limit should be imposed.
	However, since there are valid use-cases for custom properties that contain a kilobyte or more of text,
	it’s recommended that the limit be set relatively high.</p>
   <p class="note" role="note"><span>Note:</span> The general principle that UAs are allowed to violate standards due to resource constraints
	is still generally true here;
	a UA might, separately, have limits on how long of a custom property they can support,
	or how large of an identifier they can support.
	This section calls out this attack specifically
	because of its long history,
	and the fact that it can be done without any of the pieces <em>seeming</em> to be too large on first inspection.</p>
   <h2 class="heading settled" data-level="4" id="apis"><span class="secno">4. </span><span class="content"> APIs</span><a class="self-link" href="#apis"></a></h2>
   <p>All <a data-link-type="dfn" href="#custom-property" id="ref-for-custom-property③②">custom property</a> <a data-link-type="dfn" href="https://drafts.csswg.org/cssom-1/#cssstyledeclaration-declarations" id="ref-for-cssstyledeclaration-declarations">declarations</a> have the <a data-link-type="dfn" href="https://drafts.csswg.org/cssom-1/#css-declaration-case-sensitive-flag" id="ref-for-css-declaration-case-sensitive-flag">case-sensitive flag</a> set.</p>
   <p class="note" role="note"><span>Note:</span> Custom properties do not appear on a CSSStyleDeclaration object in camel-cased form,
	because their names may have both upper and lower case letters
	which indicate distinct custom properties.
	The sort of text transformation that automatic camel-casing performs is incompatible with this.
	They can still be accessed by their proper name via <a class="idl-code" data-link-type="method" href="https://drafts.csswg.org/cssom-1/#dom-cssstyledeclaration-getpropertyvalue" id="ref-for-dom-cssstyledeclaration-getpropertyvalue">getPropertyValue()</a>/etc.</p>
   <h3 class="heading settled" data-level="4.1" id="serializing-custom-props"><span class="secno">4.1. </span><span class="content"> Serializing Custom Properties</span><a class="self-link" href="#serializing-custom-props"></a></h3>
   <p>Custom property names must be serialized with the casing as provided by the author.</p>
   <p class="note" role="note"><span>Note:</span> For non-custom properties,
	property names are restricted to the ASCII range and are <a data-link-type="dfn" href="https://infra.spec.whatwg.org/#ascii-case-insensitive" id="ref-for-ascii-case-insensitive①">ASCII case-insensitive</a>,
	so implementations typically serialize the name lowercased.</p>
   <h2 class="heading settled" data-level="5" id="changes"><span class="secno">5. </span><span class="content"> Changes</span><a class="self-link" href="#changes"></a></h2>
   <h3 class="heading settled" data-level="5.1" id="changes-20151203"><span class="secno">5.1. </span><span class="content"> Changes Since the 03 December 2015 CR</span><a class="self-link" href="#changes-20151203"></a></h3>
   <ul>
    <li data-md>
     <p>Now that <a data-link-type="biblio" href="#biblio-css-syntax-3">[css-syntax-3]</a> auto-trims whitespace from declaration values,
made <a class="production css" data-link-type="type" href="https://drafts.csswg.org/css-syntax-3/#typedef-declaration-value" id="ref-for-typedef-declaration-value③">&lt;declaration-value></a> optional in the custom property grammar,
so that empty variables are still allowed.
(<a href="https://github.com/w3c/csswg-drafts/issues/774#issuecomment-434571254">Issue 774</a>)</p>
   </ul>
   <h3 class="heading settled" data-level="5.2" id="changes-20140506"><span class="secno">5.2. </span><span class="content"> Changes since the May 6 2014 Last Call Working Draft</span><a class="self-link" href="#changes-20140506"></a></h3>
   <ul>
    <li data-md>
     <p>Serialization of longhands when shorthand uses a variable was defined.</p>
    <li data-md>
     <p>Link to DOM’s definition of "case-sensitive".</p>
    <li data-md>
     <p>Added example of using variables with <a class="css" data-link-type="maybe" href="https://drafts.csswg.org/selectors-4/#lang-pseudo" id="ref-for-lang-pseudo">:lang()</a> to do simple i18n.</p>
    <li data-md>
     <p>Clarified that usage of <a class="css" data-link-type="maybe" href="#funcdef-var" id="ref-for-funcdef-var④⑥">var()</a> in a custom property must be valid per the <span class="css" id="ref-for-funcdef-var④⑦">var()</span> grammar.</p>
   </ul>
   <h2 class="heading settled" data-level="6" id="acks"><span class="secno">6. </span><span class="content"> Acknowledgments</span><a class="self-link" href="#acks"></a></h2>
   <p>Many thanks to several people in the CSS Working Group for keeping the dream of variables alive over the years,
	particularly Daniel Glazman and David Hyatt.
	Thanks to multiple people on the mailing list for helping contribute to the development of this incarnation of variables,
	particularly
	Brian Kardell,
	David Baron,
	François Remy,
	Roland Steiner,
	and Shane Stephens.</p>
   <h2 class="heading settled" data-level="7" id="priv-sec"><span class="secno">7. </span><span class="content">Privacy and Security Considerations</span><a class="self-link" href="#priv-sec"></a></h2>
   <p>This specification defines a purely author-level mechanism for passing styling information around within a page they control.
As such, there are no new privacy considerations.</p>
   <p><a href="#long-variables">§ 3.3 Safely Handling Overly-Long Variables</a> calls out a long-standing Denial-of-Service attack
that can be mounted against "macro-expansion"-like mechanisms,
such as the <a class="css" data-link-type="maybe" href="#funcdef-var" id="ref-for-funcdef-var④⑧">var()</a> function,
and mandates a defense against that attack.</p>
  </main>
  <h2 class="no-ref no-num heading settled" id="conformance"><span class="content"> Conformance</span><a class="self-link" href="#conformance"></a></h2>
  <h3 class="heading settled" id="document-conventions"><span class="content"> Document conventions</span><a class="self-link" href="#document-conventions"></a></h3>
  <p>Conformance requirements are expressed with a combination of
	descriptive assertions and RFC 2119 terminology. The key words “MUST”,
	“MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”,
	“RECOMMENDED”, “MAY”, and “OPTIONAL” in the normative parts of this
	document are to be interpreted as described in RFC 2119.
	However, for readability, these words do not appear in all uppercase
	letters in this specification. </p>
  <p>All of the text of this specification is normative except sections
	explicitly marked as non-normative, examples, and notes. <a data-link-type="biblio" href="#biblio-rfc2119">[RFC2119]</a> </p>
  <p>Examples in this specification are introduced with the words “for example”
	or are set apart from the normative text with <code class="highlight">class="example"</code>,
	like this: </p>
  <div class="example" id="example-ae2b6bc0">
   <a class="self-link" href="#example-ae2b6bc0"></a> 
   <p>This is an example of an informative example. </p>
  </div>
  <p>Informative notes begin with the word “Note” and are set apart from the
	normative text with <code class="highlight">class="note"</code>, like this: </p>
  <p class="note" role="note">Note, this is an informative note. </p>
  <p>Advisements are normative sections styled to evoke special attention and are
	set apart from other normative text with <code class="highlight">&lt;strong class="advisement"></code>, like
	this: <strong class="advisement"> UAs MUST provide an accessible alternative. </strong> </p>
  <h3 class="heading settled" id="conform-classes"><span class="content"> Conformance classes</span><a class="self-link" href="#conform-classes"></a></h3>
  <p>Conformance to this specification
	is defined for three conformance classes: </p>
  <dl>
   <dt>style sheet 
   <dd>A <a href="http://www.w3.org/TR/CSS2/conform.html#style-sheet">CSS
			style sheet</a>. 
   <dt>renderer 
   <dd>A <a href="http://www.w3.org/TR/CSS2/conform.html#user-agent">UA</a> that interprets the semantics of a style sheet and renders
			documents that use them. 
   <dt>authoring tool 
   <dd>A <a href="http://www.w3.org/TR/CSS2/conform.html#user-agent">UA</a> that writes a style sheet. 
  </dl>
  <p>A style sheet is conformant to this specification
	if all of its statements that use syntax defined in this module are valid
	according to the generic CSS grammar and the individual grammars of each
	feature defined in this module. </p>
  <p>A renderer is conformant to this specification
	if, in addition to interpreting the style sheet as defined by the
	appropriate specifications, it supports all the features defined
	by this specification by parsing them correctly
	and rendering the document accordingly. However, the inability of a
	UA to correctly render a document due to limitations of the device
	does not make the UA non-conformant. (For example, a UA is not
	required to render color on a monochrome monitor.) </p>
  <p>An authoring tool is conformant to this specification
	if it writes style sheets that are syntactically correct according to the
	generic CSS grammar and the individual grammars of each feature in
	this module, and meet all other conformance requirements of style sheets
	as described in this module. </p>
  <h3 class="heading settled" id="conform-responsible"><span class="content"> Requirements for Responsible Implementation of CSS</span><a class="self-link" href="#conform-responsible"></a></h3>
  <p>The following sections define several conformance requirements
		for implementing CSS responsibly,
		in a way that promotes interoperability in the present and future. </p>
  <h4 class="heading settled" id="conform-partial"><span class="content"> Partial Implementations</span><a class="self-link" href="#conform-partial"></a></h4>
  <p>So that authors can exploit the forward-compatible parsing rules to assign fallback values, <strong>CSS renderers <em>must</em> treat as invalid
		(and <a href="http://www.w3.org/TR/CSS2/conform.html#ignore">ignore as appropriate</a>)
		any at-rules, properties, property values, keywords, and other syntactic constructs
		for which they have no usable level of support</strong>.
		In particular, user agents <em>must not</em> selectively ignore
		unsupported property values and honor supported values in a single multi-value property declaration:
		if any value is considered invalid (as unsupported values must be),
		CSS requires that the entire declaration be ignored. </p>
  <h4 class="heading settled" id="conform-future-proofing"><span class="content"> Implementations of Unstable and Proprietary Features</span><a class="self-link" href="#conform-future-proofing"></a></h4>
  <p>To avoid clashes with future stable CSS features,
		the CSSWG recommends <a href="http://www.w3.org/TR/CSS/#future-proofing">following best practices</a> for the implementation of <a href="http://www.w3.org/TR/CSS/#unstable">unstable</a> features and <a href="http://www.w3.org/TR/CSS/#proprietary-extension">proprietary extensions</a> to CSS. </p>
  <h4 class="heading settled" id="conform-testing"><span class="content"> Implementations of CR-level Features</span><a class="self-link" href="#conform-testing"></a></h4>
  <p>Once a specification reaches the Candidate Recommendation stage,
		implementers should release an <a data-link-type="dfn" href="http://www.w3.org/TR/CSS/#vendor-prefix">unprefixed</a> implementation
		of any CR-level feature they can demonstrate
		to be correctly implemented according to spec,
		and should avoid exposing a prefixed variant of that feature. </p>
  <p>To establish and maintain the interoperability of CSS across
		implementations, the CSS Working Group requests that non-experimental
		CSS renderers submit an implementation report (and, if necessary, the
		testcases used for that implementation report) to the W3C before
		releasing an unprefixed implementation of any CSS features. Testcases
		submitted to W3C are subject to review and correction by the CSS
		Working Group. </p>
  <p>
   Further information on submitting testcases and implementation reports
		can be found from on the CSS Working Group’s website at <a href="http://www.w3.org/Style/CSS/Test/">http://www.w3.org/Style/CSS/Test/</a>.
		Questions should be directed to the <a href="http://lists.w3.org/Archives/Public/public-css-testsuite">public-css-testsuite@w3.org</a> mailing list. 
<script src="https://www.w3.org/scripts/TR/2016/fixup.js"></script>
  </p>
  <h2 class="no-num no-ref heading settled" id="index"><span class="content">Index</span><a class="self-link" href="#index"></a></h2>
  <h3 class="no-num no-ref heading settled" id="index-defined-here"><span class="content">Terms defined by this specification</span><a class="self-link" href="#index-defined-here"></a></h3>
  <ul class="index">
   <li><a href="#propdef-">--*</a><span>, in §2</span>
   <li><a href="#animation-tainted">animation-tainted</a><span>, in §2</span>
   <li><a href="#custom-property">custom property</a><span>, in §2</span>
   <li><a href="#typedef-custom-property-name">&lt;custom-property-name></a><span>, in §2</span>
   <li><a href="#cyclic-at-computed-value-time">cyclic at computed-value time</a><span>, in §2.3</span>
   <li><a href="#guaranteed-invalid-value">guaranteed-invalid value</a><span>, in §2.2</span>
   <li><a href="#invalid-at-computed-value-time">invalid at computed-value time</a><span>, in §3.1</span>
   <li><a href="#pending-substitution-value">pending-substitution value</a><span>, in §3.2</span>
   <li><a href="#substitute-a-var">substitute a var()</a><span>, in §3</span>
   <li><a href="#funcdef-var">var()</a><span>, in §3</span>
   <li><a href="#substitute-a-var">var() substitution</a><span>, in §3</span>
  </ul>
  <aside class="dfn-panel" data-for="term-for-at-ruledef-keyframes">
   <a href="https://drafts.csswg.org/css-animations-1/#at-ruledef-keyframes">https://drafts.csswg.org/css-animations-1/#at-ruledef-keyframes</a><b>Referenced in:</b>
   <ul>
    <li><a href="#ref-for-at-ruledef-keyframes">2. 
Defining Custom Properties: the --* family of properties</a>
   </ul>
  </aside>
  <aside class="dfn-panel" data-for="term-for-propdef-animation">
   <a href="https://drafts.csswg.org/css-animations-1/#propdef-animation">https://drafts.csswg.org/css-animations-1/#propdef-animation</a><b>Referenced in:</b>
   <ul>
    <li><a href="#ref-for-propdef-animation">3. 
Using Cascading Variables: the var() notation</a>
   </ul>
  </aside>
  <aside class="dfn-panel" data-for="term-for-propdef-background-color">
   <a href="https://drafts.csswg.org/css-backgrounds-3/#propdef-background-color">https://drafts.csswg.org/css-backgrounds-3/#propdef-background-color</a><b>Referenced in:</b>
   <ul>
    <li><a href="#ref-for-propdef-background-color">2. 
Defining Custom Properties: the --* family of properties</a>
    <li><a href="#ref-for-propdef-background-color①">3. 
Using Cascading Variables: the var() notation</a> <a href="#ref-for-propdef-background-color②">(2)</a>
    <li><a href="#ref-for-propdef-background-color③">3.1. 
Invalid Variables</a> <a href="#ref-for-propdef-background-color④">(2)</a> <a href="#ref-for-propdef-background-color⑤">(3)</a>
   </ul>
  </aside>
  <aside class="dfn-panel" data-for="term-for-propdef-margin-top">
   <a href="https://drafts.csswg.org/css-box-3/#propdef-margin-top">https://drafts.csswg.org/css-box-3/#propdef-margin-top</a><b>Referenced in:</b>
   <ul>
    <li><a href="#ref-for-propdef-margin-top">3. 
Using Cascading Variables: the var() notation</a> <a href="#ref-for-propdef-margin-top①">(2)</a> <a href="#ref-for-propdef-margin-top②">(3)</a> <a href="#ref-for-propdef-margin-top③">(4)</a>
   </ul>
  </aside>
  <aside class="dfn-panel" data-for="term-for-propdef-all">
   <a href="https://drafts.csswg.org/css-cascade-4/#propdef-all">https://drafts.csswg.org/css-cascade-4/#propdef-all</a><b>Referenced in:</b>
   <ul>
    <li><a href="#ref-for-propdef-all">2. 
Defining Custom Properties: the --* family of properties</a>
   </ul>
  </aside>
  <aside class="dfn-panel" data-for="term-for-cascade">
   <a href="https://drafts.csswg.org/css-cascade-4/#cascade">https://drafts.csswg.org/css-cascade-4/#cascade</a><b>Referenced in:</b>
   <ul>
    <li><a href="#ref-for-cascade">3.2. 
Variables in Shorthand Properties</a>
   </ul>
  </aside>
  <aside class="dfn-panel" data-for="term-for-valdef-all-initial">
   <a href="https://drafts.csswg.org/css-cascade-4/#valdef-all-initial">https://drafts.csswg.org/css-cascade-4/#valdef-all-initial</a><b>Referenced in:</b>
   <ul>
    <li><a href="#ref-for-valdef-all-initial">2.2. 
Guaranteed-Invalid Values</a>
   </ul>
  </aside>
  <aside class="dfn-panel" data-for="term-for-longhand">
   <a href="https://drafts.csswg.org/css-cascade-4/#longhand">https://drafts.csswg.org/css-cascade-4/#longhand</a><b>Referenced in:</b>
   <ul>
    <li><a href="#ref-for-longhand">3.2. 
Variables in Shorthand Properties</a>
   </ul>
  </aside>
  <aside class="dfn-panel" data-for="term-for-shorthand-property">
   <a href="https://drafts.csswg.org/css-cascade-4/#shorthand-property">https://drafts.csswg.org/css-cascade-4/#shorthand-property</a><b>Referenced in:</b>
   <ul>
    <li><a href="#ref-for-shorthand-property">3.2. 
Variables in Shorthand Properties</a>
   </ul>
  </aside>
  <aside class="dfn-panel" data-for="term-for-valdef-all-unset">
   <a href="https://drafts.csswg.org/css-cascade-4/#valdef-all-unset">https://drafts.csswg.org/css-cascade-4/#valdef-all-unset</a><b>Referenced in:</b>
   <ul>
    <li><a href="#ref-for-valdef-all-unset">3.1. 
Invalid Variables</a>
   </ul>
  </aside>
  <aside class="dfn-panel" data-for="term-for-propdef-color">
   <a href="https://drafts.csswg.org/css-color-4/#propdef-color">https://drafts.csswg.org/css-color-4/#propdef-color</a><b>Referenced in:</b>
   <ul>
    <li><a href="#ref-for-propdef-color">3. 
Using Cascading Variables: the var() notation</a>
   </ul>
  </aside>
  <aside class="dfn-panel" data-for="term-for-valdef-color-transparent">
   <a href="https://drafts.csswg.org/css-color-4/#valdef-color-transparent">https://drafts.csswg.org/css-color-4/#valdef-color-transparent</a><b>Referenced in:</b>
   <ul>
    <li><a href="#ref-for-valdef-color-transparent">3. 
Using Cascading Variables: the var() notation</a>
   </ul>
  </aside>
  <aside class="dfn-panel" data-for="term-for-at-ruledef-media">
   <a href="https://drafts.csswg.org/css-conditional-3/#at-ruledef-media">https://drafts.csswg.org/css-conditional-3/#at-ruledef-media</a><b>Referenced in:</b>
   <ul>
    <li><a href="#ref-for-at-ruledef-media">2. 
Defining Custom Properties: the --* family of properties</a>
   </ul>
  </aside>
  <aside class="dfn-panel" data-for="term-for-valdef-display-contents">
   <a href="https://drafts.csswg.org/css-display-3/#valdef-display-contents">https://drafts.csswg.org/css-display-3/#valdef-display-contents</a><b>Referenced in:</b>
   <ul>
    <li><a href="#ref-for-valdef-display-contents">3. 
Using Cascading Variables: the var() notation</a>
   </ul>
  </aside>
  <aside class="dfn-panel" data-for="term-for-propdef-display">
   <a href="https://drafts.csswg.org/css-display-3/#propdef-display">https://drafts.csswg.org/css-display-3/#propdef-display</a><b>Referenced in:</b>
   <ul>
    <li><a href="#ref-for-propdef-display">3. 
Using Cascading Variables: the var() notation</a>
   </ul>
  </aside>
  <aside class="dfn-panel" data-for="term-for-valdef-display-none">
   <a href="https://drafts.csswg.org/css-display-3/#valdef-display-none">https://drafts.csswg.org/css-display-3/#valdef-display-none</a><b>Referenced in:</b>
   <ul>
    <li><a href="#ref-for-valdef-display-none">3. 
Using Cascading Variables: the var() notation</a>
   </ul>
  </aside>
  <aside class="dfn-panel" data-for="term-for-propdef-font-size">
   <a href="https://drafts.csswg.org/css-fonts-3/#propdef-font-size">https://drafts.csswg.org/css-fonts-3/#propdef-font-size</a><b>Referenced in:</b>
   <ul>
    <li><a href="#ref-for-propdef-font-size">2.3. 
Resolving Dependency Cycles</a>
   </ul>
  </aside>
  <aside class="dfn-panel" data-for="term-for-tokendef-close-paren">
   <a href="https://drafts.csswg.org/css-syntax-3/#tokendef-close-paren">https://drafts.csswg.org/css-syntax-3/#tokendef-close-paren</a><b>Referenced in:</b>
   <ul>
    <li><a href="#ref-for-tokendef-close-paren">2.1. 
Custom Property Value Syntax</a>
   </ul>
  </aside>
  <aside class="dfn-panel" data-for="term-for-tokendef-close-square">
   <a href="https://drafts.csswg.org/css-syntax-3/#tokendef-close-square">https://drafts.csswg.org/css-syntax-3/#tokendef-close-square</a><b>Referenced in:</b>
   <ul>
    <li><a href="#ref-for-tokendef-close-square">2.1. 
Custom Property Value Syntax</a>
   </ul>
  </aside>
  <aside class="dfn-panel" data-for="term-for-typedef-bad-string-token">
   <a href="https://drafts.csswg.org/css-syntax-3/#typedef-bad-string-token">https://drafts.csswg.org/css-syntax-3/#typedef-bad-string-token</a><b>Referenced in:</b>
   <ul>
    <li><a href="#ref-for-typedef-bad-string-token">2.1. 
Custom Property Value Syntax</a>
   </ul>
  </aside>
  <aside class="dfn-panel" data-for="term-for-typedef-bad-url-token">
   <a href="https://drafts.csswg.org/css-syntax-3/#typedef-bad-url-token">https://drafts.csswg.org/css-syntax-3/#typedef-bad-url-token</a><b>Referenced in:</b>
   <ul>
    <li><a href="#ref-for-typedef-bad-url-token">2.1. 
Custom Property Value Syntax</a>
   </ul>
  </aside>
  <aside class="dfn-panel" data-for="term-for-typedef-declaration-value">
   <a href="https://drafts.csswg.org/css-syntax-3/#typedef-declaration-value">https://drafts.csswg.org/css-syntax-3/#typedef-declaration-value</a><b>Referenced in:</b>
   <ul>
    <li><a href="#ref-for-typedef-declaration-value">2. 
Defining Custom Properties: the --* family of properties</a>
    <li><a href="#ref-for-typedef-declaration-value①">2.1. 
Custom Property Value Syntax</a>
    <li><a href="#ref-for-typedef-declaration-value②">3. 
Using Cascading Variables: the var() notation</a>
    <li><a href="#ref-for-typedef-declaration-value③">5.1. 
Changes Since the 03 December 2015 CR</a>
   </ul>
  </aside>
  <aside class="dfn-panel" data-for="term-for-typedef-delim-token">
   <a href="https://drafts.csswg.org/css-syntax-3/#typedef-delim-token">https://drafts.csswg.org/css-syntax-3/#typedef-delim-token</a><b>Referenced in:</b>
   <ul>
    <li><a href="#ref-for-typedef-delim-token">2.1. 
Custom Property Value Syntax</a>
   </ul>
  </aside>
  <aside class="dfn-panel" data-for="term-for-typedef-semicolon-token">
   <a href="https://drafts.csswg.org/css-syntax-3/#typedef-semicolon-token">https://drafts.csswg.org/css-syntax-3/#typedef-semicolon-token</a><b>Referenced in:</b>
   <ul>
    <li><a href="#ref-for-typedef-semicolon-token">2.1. 
Custom Property Value Syntax</a>
   </ul>
  </aside>
  <aside class="dfn-panel" data-for="term-for-tokendef-close-curly">
   <a href="https://drafts.csswg.org/css-syntax-3/#tokendef-close-curly">https://drafts.csswg.org/css-syntax-3/#tokendef-close-curly</a><b>Referenced in:</b>
   <ul>
    <li><a href="#ref-for-tokendef-close-curly">2.1. 
Custom Property Value Syntax</a>
   </ul>
  </aside>
  <aside class="dfn-panel" data-for="term-for-identifier">
   <a href="https://drafts.csswg.org/css-syntax-3/#identifier">https://drafts.csswg.org/css-syntax-3/#identifier</a><b>Referenced in:</b>
   <ul>
    <li><a href="#ref-for-identifier">2. 
Defining Custom Properties: the --* family of properties</a>
   </ul>
  </aside>
  <aside class="dfn-panel" data-for="term-for-comb-comma">
   <a href="https://drafts.csswg.org/css-values-4/#comb-comma">https://drafts.csswg.org/css-values-4/#comb-comma</a><b>Referenced in:</b>
   <ul>
    <li><a href="#ref-for-comb-comma">3. 
Using Cascading Variables: the var() notation</a>
   </ul>
  </aside>
  <aside class="dfn-panel" data-for="term-for-mult-opt">
   <a href="https://drafts.csswg.org/css-values-4/#mult-opt">https://drafts.csswg.org/css-values-4/#mult-opt</a><b>Referenced in:</b>
   <ul>
    <li><a href="#ref-for-mult-opt">2. 
Defining Custom Properties: the --* family of properties</a>
    <li><a href="#ref-for-mult-opt①">3. 
Using Cascading Variables: the var() notation</a>
   </ul>
  </aside>
  <aside class="dfn-panel" data-for="term-for-funcdef-calc">
   <a href="https://drafts.csswg.org/css-values-4/#funcdef-calc">https://drafts.csswg.org/css-values-4/#funcdef-calc</a><b>Referenced in:</b>
   <ul>
    <li><a href="#ref-for-funcdef-calc">3. 
Using Cascading Variables: the var() notation</a>
   </ul>
  </aside>
  <aside class="dfn-panel" data-for="term-for-css-wide-keywords">
   <a href="https://drafts.csswg.org/css-values-4/#css-wide-keywords">https://drafts.csswg.org/css-values-4/#css-wide-keywords</a><b>Referenced in:</b>
   <ul>
    <li><a href="#ref-for-css-wide-keywords">2. 
Defining Custom Properties: the --* family of properties</a>
   </ul>
  </aside>
  <aside class="dfn-panel" data-for="term-for-em">
   <a href="https://drafts.csswg.org/css-values-4/#em">https://drafts.csswg.org/css-values-4/#em</a><b>Referenced in:</b>
   <ul>
    <li><a href="#ref-for-em">2.3. 
Resolving Dependency Cycles</a>
   </ul>
  </aside>
  <aside class="dfn-panel" data-for="term-for-css-declaration-case-sensitive-flag">
   <a href="https://drafts.csswg.org/cssom-1/#css-declaration-case-sensitive-flag">https://drafts.csswg.org/cssom-1/#css-declaration-case-sensitive-flag</a><b>Referenced in:</b>
   <ul>
    <li><a href="#ref-for-css-declaration-case-sensitive-flag">4. 
APIs</a>
   </ul>
  </aside>
  <aside class="dfn-panel" data-for="term-for-cssstyledeclaration-declarations">
   <a href="https://drafts.csswg.org/cssom-1/#cssstyledeclaration-declarations">https://drafts.csswg.org/cssom-1/#cssstyledeclaration-declarations</a><b>Referenced in:</b>
   <ul>
    <li><a href="#ref-for-cssstyledeclaration-declarations">4. 
APIs</a>
   </ul>
  </aside>
  <aside class="dfn-panel" data-for="term-for-dom-cssstyledeclaration-getpropertyvalue">
   <a href="https://drafts.csswg.org/cssom-1/#dom-cssstyledeclaration-getpropertyvalue">https://drafts.csswg.org/cssom-1/#dom-cssstyledeclaration-getpropertyvalue</a><b>Referenced in:</b>
   <ul>
    <li><a href="#ref-for-dom-cssstyledeclaration-getpropertyvalue">4. 
APIs</a>
   </ul>
  </aside>
  <aside class="dfn-panel" data-for="term-for-case-sensitive">
   <a href="https://html.spec.whatwg.org/multipage/infrastructure.html#case-sensitive">https://html.spec.whatwg.org/multipage/infrastructure.html#case-sensitive</a><b>Referenced in:</b>
   <ul>
    <li><a href="#ref-for-case-sensitive">2. 
Defining Custom Properties: the --* family of properties</a>
   </ul>
  </aside>
  <aside class="dfn-panel" data-for="term-for-ascii-case-insensitive">
   <a href="https://infra.spec.whatwg.org/#ascii-case-insensitive">https://infra.spec.whatwg.org/#ascii-case-insensitive</a><b>Referenced in:</b>
   <ul>
    <li><a href="#ref-for-ascii-case-insensitive">2.1. 
Custom Property Value Syntax</a>
    <li><a href="#ref-for-ascii-case-insensitive①">4.1. 
Serializing Custom Properties</a>
   </ul>
  </aside>
  <aside class="dfn-panel" data-for="term-for-lang-pseudo">
   <a href="https://drafts.csswg.org/selectors-4/#lang-pseudo">https://drafts.csswg.org/selectors-4/#lang-pseudo</a><b>Referenced in:</b>
   <ul>
    <li><a href="#ref-for-lang-pseudo">5.2. 
Changes since the May 6 2014 Last Call Working Draft</a>
   </ul>
  </aside>
  <h3 class="no-num no-ref heading settled" id="index-defined-elsewhere"><span class="content">Terms defined by reference</span><a class="self-link" href="#index-defined-elsewhere"></a></h3>
  <ul class="index">
   <li>
    <a data-link-type="biblio">[css-animations-1]</a> defines the following terms:
    <ul>
     <li><span class="dfn-paneled" id="term-for-at-ruledef-keyframes" style="color:initial">@keyframes</span>
     <li><span class="dfn-paneled" id="term-for-propdef-animation" style="color:initial">animation</span>
    </ul>
   <li>
    <a data-link-type="biblio">[css-backgrounds-3]</a> defines the following terms:
    <ul>
     <li><span class="dfn-paneled" id="term-for-propdef-background-color" style="color:initial">background-color</span>
    </ul>
   <li>
    <a data-link-type="biblio">[css-box-3]</a> defines the following terms:
    <ul>
     <li><span class="dfn-paneled" id="term-for-propdef-margin-top" style="color:initial">margin-top</span>
    </ul>
   <li>
    <a data-link-type="biblio">[css-cascade-4]</a> defines the following terms:
    <ul>
     <li><span class="dfn-paneled" id="term-for-propdef-all" style="color:initial">all</span>
     <li><span class="dfn-paneled" id="term-for-cascade" style="color:initial">cascade</span>
     <li><span class="dfn-paneled" id="term-for-valdef-all-initial" style="color:initial">initial</span>
     <li><span class="dfn-paneled" id="term-for-longhand" style="color:initial">longhand property</span>
     <li><span class="dfn-paneled" id="term-for-shorthand-property" style="color:initial">shorthand property</span>
     <li><span class="dfn-paneled" id="term-for-valdef-all-unset" style="color:initial">unset</span>
    </ul>
   <li>
    <a data-link-type="biblio">[css-color-4]</a> defines the following terms:
    <ul>
     <li><span class="dfn-paneled" id="term-for-propdef-color" style="color:initial">color</span>
     <li><span class="dfn-paneled" id="term-for-valdef-color-transparent" style="color:initial">transparent</span>
    </ul>
   <li>
    <a data-link-type="biblio">[css-conditional-3]</a> defines the following terms:
    <ul>
     <li><span class="dfn-paneled" id="term-for-at-ruledef-media" style="color:initial">@media</span>
    </ul>
   <li>
    <a data-link-type="biblio">[css-display-3]</a> defines the following terms:
    <ul>
     <li><span class="dfn-paneled" id="term-for-valdef-display-contents" style="color:initial">contents</span>
     <li><span class="dfn-paneled" id="term-for-propdef-display" style="color:initial">display</span>
     <li><span class="dfn-paneled" id="term-for-valdef-display-none" style="color:initial">none</span>
    </ul>
   <li>
    <a data-link-type="biblio">[css-fonts-3]</a> defines the following terms:
    <ul>
     <li><span class="dfn-paneled" id="term-for-propdef-font-size" style="color:initial">font-size</span>
    </ul>
   <li>
    <a data-link-type="biblio">[css-syntax-3]</a> defines the following terms:
    <ul>
     <li><span class="dfn-paneled" id="term-for-tokendef-close-paren" style="color:initial">&lt;)-token></span>
     <li><span class="dfn-paneled" id="term-for-tokendef-close-square" style="color:initial">&lt;]-token></span>
     <li><span class="dfn-paneled" id="term-for-typedef-bad-string-token" style="color:initial">&lt;bad-string-token></span>
     <li><span class="dfn-paneled" id="term-for-typedef-bad-url-token" style="color:initial">&lt;bad-url-token></span>
     <li><span class="dfn-paneled" id="term-for-typedef-declaration-value" style="color:initial">&lt;declaration-value></span>
     <li><span class="dfn-paneled" id="term-for-typedef-delim-token" style="color:initial">&lt;delim-token></span>
     <li><span class="dfn-paneled" id="term-for-typedef-semicolon-token" style="color:initial">&lt;semicolon-token></span>
     <li><span class="dfn-paneled" id="term-for-tokendef-close-curly" style="color:initial">&lt;}-token></span>
     <li><span class="dfn-paneled" id="term-for-identifier" style="color:initial">identifier</span>
    </ul>
   <li>
    <a data-link-type="biblio">[css-values-4]</a> defines the following terms:
    <ul>
     <li><span class="dfn-paneled" id="term-for-comb-comma" style="color:initial">,</span>
     <li><span class="dfn-paneled" id="term-for-mult-opt" style="color:initial">?</span>
     <li><span class="dfn-paneled" id="term-for-funcdef-calc" style="color:initial">calc()</span>
     <li><span class="dfn-paneled" id="term-for-css-wide-keywords" style="color:initial">css-wide keywords</span>
     <li><span class="dfn-paneled" id="term-for-em" style="color:initial">em</span>
    </ul>
   <li>
    <a data-link-type="biblio">[CSSOM]</a> defines the following terms:
    <ul>
     <li><span class="dfn-paneled" id="term-for-css-declaration-case-sensitive-flag" style="color:initial">case-sensitive flag</span>
     <li><span class="dfn-paneled" id="term-for-cssstyledeclaration-declarations" style="color:initial">declarations</span>
     <li><span class="dfn-paneled" id="term-for-dom-cssstyledeclaration-getpropertyvalue" style="color:initial">getPropertyValue(property)</span>
    </ul>
   <li>
    <a data-link-type="biblio">[HTML]</a> defines the following terms:
    <ul>
     <li><span class="dfn-paneled" id="term-for-case-sensitive" style="color:initial">case-sensitive</span>
    </ul>
   <li>
    <a data-link-type="biblio">[INFRA]</a> defines the following terms:
    <ul>
     <li><span class="dfn-paneled" id="term-for-ascii-case-insensitive" style="color:initial">ascii case-insensitive</span>
    </ul>
   <li>
    <a data-link-type="biblio">[selectors-4]</a> defines the following terms:
    <ul>
     <li><span class="dfn-paneled" id="term-for-lang-pseudo" style="color:initial">:lang()</span>
    </ul>
  </ul>
  <h2 class="no-num no-ref heading settled" id="references"><span class="content">References</span><a class="self-link" href="#references"></a></h2>
  <h3 class="no-num no-ref heading settled" id="normative"><span class="content">Normative References</span><a class="self-link" href="#normative"></a></h3>
  <dl>
   <dt id="biblio-css-animations-1">[CSS-ANIMATIONS-1]
   <dd>Dean Jackson; et al. <a href="https://www.w3.org/TR/css-animations-1/">CSS Animations Level 1</a>. 11 October 2018. WD. URL: <a href="https://www.w3.org/TR/css-animations-1/">https://www.w3.org/TR/css-animations-1/</a>
   <dt id="biblio-css-cascade-4">[CSS-CASCADE-4]
   <dd>Elika Etemad; Tab Atkins Jr.. <a href="https://www.w3.org/TR/css-cascade-4/">CSS Cascading and Inheritance Level 4</a>. 28 August 2018. CR. URL: <a href="https://www.w3.org/TR/css-cascade-4/">https://www.w3.org/TR/css-cascade-4/</a>
   <dt id="biblio-css-conditional-3">[CSS-CONDITIONAL-3]
   <dd>CSS Conditional Rules Module Level 3 URL: <a href="https://www.w3.org/TR/css3-conditional/">https://www.w3.org/TR/css3-conditional/</a>
   <dt id="biblio-css-display-3">[CSS-DISPLAY-3]
   <dd>Tab Atkins Jr.; Elika Etemad. <a href="https://www.w3.org/TR/css-display-3/">CSS Display Module Level 3</a>. 28 August 2018. CR. URL: <a href="https://www.w3.org/TR/css-display-3/">https://www.w3.org/TR/css-display-3/</a>
   <dt id="biblio-css-syntax-3">[CSS-SYNTAX-3]
   <dd>Tab Atkins Jr.; Simon Sapin. <a href="https://www.w3.org/TR/css-syntax-3/">CSS Syntax Module Level 3</a>. 20 February 2014. CR. URL: <a href="https://www.w3.org/TR/css-syntax-3/">https://www.w3.org/TR/css-syntax-3/</a>
   <dt id="biblio-css-values-4">[CSS-VALUES-4]
   <dd>Tab Atkins Jr.; Elika Etemad. <a href="https://www.w3.org/TR/css-values-4/">CSS Values and Units Module Level 4</a>. 31 January 2019. WD. URL: <a href="https://www.w3.org/TR/css-values-4/">https://www.w3.org/TR/css-values-4/</a>
   <dt id="biblio-cssom">[CSSOM]
   <dd>Simon Pieters; Glenn Adams. <a href="https://www.w3.org/TR/cssom-1/">CSS Object Model (CSSOM)</a>. 17 March 2016. WD. URL: <a href="https://www.w3.org/TR/cssom-1/">https://www.w3.org/TR/cssom-1/</a>
   <dt id="biblio-html">[HTML]
   <dd>Anne van Kesteren; et al. <a href="https://html.spec.whatwg.org/multipage/">HTML Standard</a>. Living Standard. URL: <a href="https://html.spec.whatwg.org/multipage/">https://html.spec.whatwg.org/multipage/</a>
   <dt id="biblio-infra">[INFRA]
   <dd>Anne van Kesteren; Domenic Denicola. <a href="https://infra.spec.whatwg.org/">Infra Standard</a>. Living Standard. URL: <a href="https://infra.spec.whatwg.org/">https://infra.spec.whatwg.org/</a>
   <dt id="biblio-rfc2119">[RFC2119]
   <dd>S. Bradner. <a href="https://tools.ietf.org/html/rfc2119">Key words for use in RFCs to Indicate Requirement Levels</a>. March 1997. Best Current Practice. URL: <a href="https://tools.ietf.org/html/rfc2119">https://tools.ietf.org/html/rfc2119</a>
   <dt id="biblio-selectors-4">[SELECTORS-4]
   <dd>Elika Etemad; Tab Atkins Jr.. <a href="https://www.w3.org/TR/selectors-4/">Selectors Level 4</a>. 21 November 2018. WD. URL: <a href="https://www.w3.org/TR/selectors-4/">https://www.w3.org/TR/selectors-4/</a>
  </dl>
  <h3 class="no-num no-ref heading settled" id="informative"><span class="content">Informative References</span><a class="self-link" href="#informative"></a></h3>
  <dl>
   <dt id="biblio-css-backgrounds-3">[CSS-BACKGROUNDS-3]
   <dd>Bert Bos; Elika Etemad; Brad Kemper. <a href="https://www.w3.org/TR/css-backgrounds-3/">CSS Backgrounds and Borders Module Level 3</a>. 17 October 2017. CR. URL: <a href="https://www.w3.org/TR/css-backgrounds-3/">https://www.w3.org/TR/css-backgrounds-3/</a>
   <dt id="biblio-css-box-3">[CSS-BOX-3]
   <dd>Elika Etemad. <a href="https://www.w3.org/TR/css-box-3/">CSS Box Model Module Level 3</a>. 18 December 2018. WD. URL: <a href="https://www.w3.org/TR/css-box-3/">https://www.w3.org/TR/css-box-3/</a>
   <dt id="biblio-css-color-4">[CSS-COLOR-4]
   <dd>Tab Atkins Jr.; Chris Lilley. <a href="https://www.w3.org/TR/css-color-4/">CSS Color Module Level 4</a>. 5 March 2019. WD. URL: <a href="https://www.w3.org/TR/css-color-4/">https://www.w3.org/TR/css-color-4/</a>
   <dt id="biblio-css-extensions">[CSS-EXTENSIONS]
   <dd>Tab Atkins Jr.. <a href="https://drafts.csswg.org/css-extensions/">CSS Extensions</a>. ED. URL: <a href="https://drafts.csswg.org/css-extensions/">https://drafts.csswg.org/css-extensions/</a>
   <dt id="biblio-css-fonts-3">[CSS-FONTS-3]
   <dd>John Daggett; Myles Maxfield; Chris Lilley. <a href="https://www.w3.org/TR/css-fonts-3/">CSS Fonts Module Level 3</a>. 20 September 2018. REC. URL: <a href="https://www.w3.org/TR/css-fonts-3/">https://www.w3.org/TR/css-fonts-3/</a>
  </dl>
  <h2 class="no-num no-ref heading settled" id="property-index"><span class="content">Property Index</span><a class="self-link" href="#property-index"></a></h2>
  <div class="big-element-wrapper">
   <table class="index">
    <thead>
     <tr>
      <th scope="col">Name
      <th scope="col">Value
      <th scope="col">Initial
      <th scope="col">Applies to
      <th scope="col">Inh.
      <th scope="col">%ages
      <th scope="col">Ani­mat­able
      <th scope="col">Canonical order
      <th scope="col">Com­puted value
    <tbody>
     <tr>
      <th scope="row"><a class="css" data-link-type="property">--*</a>
      <td>&lt;declaration-value>?
      <td>the guaranteed-invalid value
      <td>all elements
      <td>yes
      <td>n/a
      <td>no
      <td>per grammar
      <td>specified value with variables substituted, or the guaranteed-invalid value
   </table>
  </div>
  <aside class="dfn-panel" data-for="custom-property">
   <b><a href="#custom-property">#custom-property</a></b><b>Referenced in:</b>
   <ul>
    <li><a href="#ref-for-custom-property">1. 
Introduction</a> <a href="#ref-for-custom-property①">(2)</a>
    <li><a href="#ref-for-custom-property②">2. 
Defining Custom Properties: the --* family of properties</a> <a href="#ref-for-custom-property③">(2)</a> <a href="#ref-for-custom-property④">(3)</a> <a href="#ref-for-custom-property⑤">(4)</a> <a href="#ref-for-custom-property⑥">(5)</a> <a href="#ref-for-custom-property⑦">(6)</a> <a href="#ref-for-custom-property⑧">(7)</a>
    <li><a href="#ref-for-custom-property⑨">2.1. 
Custom Property Value Syntax</a> <a href="#ref-for-custom-property①⓪">(2)</a> <a href="#ref-for-custom-property①①">(3)</a>
    <li><a href="#ref-for-custom-property①②">2.2. 
Guaranteed-Invalid Values</a> <a href="#ref-for-custom-property①③">(2)</a>
    <li><a href="#ref-for-custom-property①④">2.3. 
Resolving Dependency Cycles</a> <a href="#ref-for-custom-property①⑤">(2)</a> <a href="#ref-for-custom-property①⑥">(3)</a> <a href="#ref-for-custom-property①⑦">(4)</a> <a href="#ref-for-custom-property①⑧">(5)</a> <a href="#ref-for-custom-property①⑨">(6)</a>
    <li><a href="#ref-for-custom-property②⓪">3. 
Using Cascading Variables: the var() notation</a> <a href="#ref-for-custom-property②①">(2)</a> <a href="#ref-for-custom-property②②">(3)</a> <a href="#ref-for-custom-property②③">(4)</a> <a href="#ref-for-custom-property②④">(5)</a> <a href="#ref-for-custom-property②⑤">(6)</a> <a href="#ref-for-custom-property②⑥">(7)</a> <a href="#ref-for-custom-property②⑦">(8)</a>
    <li><a href="#ref-for-custom-property②⑧">3.1. 
Invalid Variables</a> <a href="#ref-for-custom-property②⑨">(2)</a> <a href="#ref-for-custom-property③⓪">(3)</a> <a href="#ref-for-custom-property③①">(4)</a>
    <li><a href="#ref-for-custom-property③②">4. 
APIs</a>
   </ul>
  </aside>
  <aside class="dfn-panel" data-for="typedef-custom-property-name">
   <b><a href="#typedef-custom-property-name">#typedef-custom-property-name</a></b><b>Referenced in:</b>
   <ul>
    <li><a href="#ref-for-typedef-custom-property-name">3. 
Using Cascading Variables: the var() notation</a>
   </ul>
  </aside>
  <aside class="dfn-panel" data-for="animation-tainted">
   <b><a href="#animation-tainted">#animation-tainted</a></b><b>Referenced in:</b>
   <ul>
    <li><a href="#ref-for-animation-tainted">3. 
Using Cascading Variables: the var() notation</a>
   </ul>
  </aside>
  <aside class="dfn-panel" data-for="guaranteed-invalid-value">
   <b><a href="#guaranteed-invalid-value">#guaranteed-invalid-value</a></b><b>Referenced in:</b>
   <ul>
    <li><a href="#ref-for-guaranteed-invalid-value">2. 
Defining Custom Properties: the --* family of properties</a> <a href="#ref-for-guaranteed-invalid-value①">(2)</a>
    <li><a href="#ref-for-guaranteed-invalid-value②">2.2. 
Guaranteed-Invalid Values</a> <a href="#ref-for-guaranteed-invalid-value③">(2)</a>
    <li><a href="#ref-for-guaranteed-invalid-value④">2.3. 
Resolving Dependency Cycles</a> <a href="#ref-for-guaranteed-invalid-value⑤">(2)</a> <a href="#ref-for-guaranteed-invalid-value⑥">(3)</a>
    <li><a href="#ref-for-guaranteed-invalid-value⑦">3. 
Using Cascading Variables: the var() notation</a>
    <li><a href="#ref-for-guaranteed-invalid-value⑧">3.1. 
Invalid Variables</a> <a href="#ref-for-guaranteed-invalid-value⑨">(2)</a>
   </ul>
  </aside>
  <aside class="dfn-panel" data-for="cyclic-at-computed-value-time">
   <b><a href="#cyclic-at-computed-value-time">#cyclic-at-computed-value-time</a></b><b>Referenced in:</b>
   <ul>
    <li><a href="#ref-for-cyclic-at-computed-value-time">2.3. 
Resolving Dependency Cycles</a>
   </ul>
  </aside>
  <aside class="dfn-panel" data-for="funcdef-var">
   <b><a href="#funcdef-var">#funcdef-var</a></b><b>Referenced in:</b>
   <ul>
    <li><a href="#ref-for-funcdef-var">1. 
Introduction</a>
    <li><a href="#ref-for-funcdef-var①">2. 
Defining Custom Properties: the --* family of properties</a> <a href="#ref-for-funcdef-var②">(2)</a> <a href="#ref-for-funcdef-var③">(3)</a> <a href="#ref-for-funcdef-var④">(4)</a> <a href="#ref-for-funcdef-var⑤">(5)</a>
    <li><a href="#ref-for-funcdef-var⑥">2.1. 
Custom Property Value Syntax</a> <a href="#ref-for-funcdef-var⑦">(2)</a> <a href="#ref-for-funcdef-var⑧">(3)</a> <a href="#ref-for-funcdef-var⑨">(4)</a>
    <li><a href="#ref-for-funcdef-var①⓪">2.2. 
Guaranteed-Invalid Values</a>
    <li><a href="#ref-for-funcdef-var①①">2.3. 
Resolving Dependency Cycles</a> <a href="#ref-for-funcdef-var①②">(2)</a> <a href="#ref-for-funcdef-var①③">(3)</a> <a href="#ref-for-funcdef-var①④">(4)</a> <a href="#ref-for-funcdef-var①⑤">(5)</a>
    <li><a href="#ref-for-funcdef-var①⑥">3. 
Using Cascading Variables: the var() notation</a> <a href="#ref-for-funcdef-var①⑦">(2)</a> <a href="#ref-for-funcdef-var①⑧">(3)</a> <a href="#ref-for-funcdef-var①⑨">(4)</a> <a href="#ref-for-funcdef-var②⓪">(5)</a> <a href="#ref-for-funcdef-var②①">(6)</a> <a href="#ref-for-funcdef-var②②">(7)</a> <a href="#ref-for-funcdef-var②③">(8)</a> <a href="#ref-for-funcdef-var②④">(9)</a> <a href="#ref-for-funcdef-var②⑤">(10)</a> <a href="#ref-for-funcdef-var②⑥">(11)</a> <a href="#ref-for-funcdef-var②⑦">(12)</a> <a href="#ref-for-funcdef-var②⑧">(13)</a> <a href="#ref-for-funcdef-var②⑨">(14)</a> <a href="#ref-for-funcdef-var③⓪">(15)</a> <a href="#ref-for-funcdef-var③①">(16)</a> <a href="#ref-for-funcdef-var③②">(17)</a>
    <li><a href="#ref-for-funcdef-var③③">3.1. 
Invalid Variables</a> <a href="#ref-for-funcdef-var③④">(2)</a> <a href="#ref-for-funcdef-var③⑤">(3)</a> <a href="#ref-for-funcdef-var③⑥">(4)</a>
    <li><a href="#ref-for-funcdef-var③⑦">3.2. 
Variables in Shorthand Properties</a> <a href="#ref-for-funcdef-var③⑧">(2)</a> <a href="#ref-for-funcdef-var③⑨">(3)</a> <a href="#ref-for-funcdef-var④⓪">(4)</a> <a href="#ref-for-funcdef-var④①">(5)</a> <a href="#ref-for-funcdef-var④②">(6)</a>
    <li><a href="#ref-for-funcdef-var④③">3.3. 
Safely Handling Overly-Long Variables</a> <a href="#ref-for-funcdef-var④④">(2)</a> <a href="#ref-for-funcdef-var④⑤">(3)</a>
    <li><a href="#ref-for-funcdef-var④⑥">5.2. 
Changes since the May 6 2014 Last Call Working Draft</a> <a href="#ref-for-funcdef-var④⑦">(2)</a>
    <li><a href="#ref-for-funcdef-var④⑧">7. Privacy and Security Considerations</a>
   </ul>
  </aside>
  <aside class="dfn-panel" data-for="substitute-a-var">
   <b><a href="#substitute-a-var">#substitute-a-var</a></b><b>Referenced in:</b>
   <ul>
    <li><a href="#ref-for-substitute-a-var">2. 
Defining Custom Properties: the --* family of properties</a>
    <li><a href="#ref-for-substitute-a-var①">3. 
Using Cascading Variables: the var() notation</a> <a href="#ref-for-substitute-a-var②">(2)</a> <a href="#ref-for-substitute-a-var③">(3)</a> <a href="#ref-for-substitute-a-var④">(4)</a>
   </ul>
  </aside>
  <aside class="dfn-panel" data-for="invalid-at-computed-value-time">
   <b><a href="#invalid-at-computed-value-time">#invalid-at-computed-value-time</a></b><b>Referenced in:</b>
   <ul>
    <li><a href="#ref-for-invalid-at-computed-value-time">2.2. 
Guaranteed-Invalid Values</a>
    <li><a href="#ref-for-invalid-at-computed-value-time①">2.3. 
Resolving Dependency Cycles</a>
    <li><a href="#ref-for-invalid-at-computed-value-time②">3. 
Using Cascading Variables: the var() notation</a> <a href="#ref-for-invalid-at-computed-value-time③">(2)</a> <a href="#ref-for-invalid-at-computed-value-time④">(3)</a>
    <li><a href="#ref-for-invalid-at-computed-value-time⑤">3.1. 
Invalid Variables</a> <a href="#ref-for-invalid-at-computed-value-time⑥">(2)</a>
    <li><a href="#ref-for-invalid-at-computed-value-time⑦">3.3. 
Safely Handling Overly-Long Variables</a>
   </ul>
  </aside>
  <aside class="dfn-panel" data-for="pending-substitution-value">
   <b><a href="#pending-substitution-value">#pending-substitution-value</a></b><b>Referenced in:</b>
   <ul>
    <li><a href="#ref-for-pending-substitution-value">3.2. 
Variables in Shorthand Properties</a> <a href="#ref-for-pending-substitution-value①">(2)</a>
   </ul>
  </aside>
<script>/* script-dfn-panel */

document.body.addEventListener("click", function(e) {
    var queryAll = function(sel) { return [].slice.call(document.querySelectorAll(sel)); }
    // Find the dfn element or panel, if any, that was clicked on.
    var el = e.target;
    var target;
    var hitALink = false;
    while(el.parentElement) {
        if(el.tagName == "A") {
            // Clicking on a link in a <dfn> shouldn't summon the panel
            hitALink = true;
        }
        if(el.classList.contains("dfn-paneled")) {
            target = "dfn";
            break;
        }
        if(el.classList.contains("dfn-panel")) {
            target = "dfn-panel";
            break;
        }
        el = el.parentElement;
    }
    if(target != "dfn-panel") {
        // Turn off any currently "on" or "activated" panels.
        queryAll(".dfn-panel.on, .dfn-panel.activated").forEach(function(el){
            el.classList.remove("on");
            el.classList.remove("activated");
        });
    }
    if(target == "dfn" && !hitALink) {
        // open the panel
        var dfnPanel = document.querySelector(".dfn-panel[data-for='" + el.id + "']");
        if(dfnPanel) {
            dfnPanel.classList.add("on");
            var rect = el.getBoundingClientRect();
            dfnPanel.style.left = window.scrollX + rect.right + 5 + "px";
            dfnPanel.style.top = window.scrollY + rect.top + "px";
            var panelRect = dfnPanel.getBoundingClientRect();
            var panelWidth = panelRect.right - panelRect.left;
            if(panelRect.right > document.body.scrollWidth && (rect.left - (panelWidth + 5)) > 0) {
                // Reposition, because the panel is overflowing
                dfnPanel.style.left = window.scrollX + rect.left - (panelWidth + 5) + "px";
            }
        } else {
            console.log("Couldn't find .dfn-panel[data-for='" + el.id + "']");
        }
    } else if(target == "dfn-panel") {
        // Switch it to "activated" state, which pins it.
        el.classList.add("activated");
        el.style.left = null;
        el.style.top = null;
    }

});
</script>